3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
21 namespace MediaWiki\Shell
;
24 use MediaWiki\ProcOpenError
;
25 use MediaWiki\ShellDisabledError
;
27 use Psr\Log\LoggerAwareTrait
;
28 use Psr\Log\NullLogger
;
31 * Class used for executing shell commands
39 protected $command = '';
60 private $doIncludeStderr = false;
63 private $doLogStderr = false;
66 private $everExecuted = false;
68 /** @var string|false */
69 private $cgroup = false;
72 * bitfield with restrictions
76 protected $restrictions = 0;
79 * Constructor. Don't call directly, instead use Shell::command()
81 * @throws ShellDisabledError
83 public function __construct() {
84 if ( Shell
::isDisabled() ) {
85 throw new ShellDisabledError();
88 $this->setLogger( new NullLogger() );
92 * Destructor. Makes sure programmer didn't forget to execute the command after all
94 public function __destruct() {
95 if ( !$this->everExecuted
) {
96 $context = [ 'command' => $this->command
];
97 $message = __CLASS__
. " was instantiated, but execute() was never called.";
98 if ( $this->method
) {
99 $message .= ' Calling method: {method}.';
100 $context['method'] = $this->method
;
102 $message .= ' Command: {command}';
103 $this->logger
->warning( $message, $context );
108 * Adds parameters to the command. All parameters are sanitized via Shell::escape().
109 * Null values are ignored.
111 * @param string|string[] $args,...
114 public function params( /* ... */ ) {
115 $args = func_get_args();
116 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
117 // If only one argument has been passed, and that argument is an array,
118 // treat it as a list of arguments
119 $args = reset( $args );
121 $this->command
= trim( $this->command
. ' ' . Shell
::escape( $args ) );
127 * Adds unsafe parameters to the command. These parameters are NOT sanitized in any way.
128 * Null values are ignored.
130 * @param string|string[] $args,...
133 public function unsafeParams( /* ... */ ) {
134 $args = func_get_args();
135 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
136 // If only one argument has been passed, and that argument is an array,
137 // treat it as a list of arguments
138 $args = reset( $args );
140 $args = array_filter( $args,
141 function ( $value ) {
142 return $value !== null;
145 $this->command
= trim( $this->command
. ' ' . implode( ' ', $args ) );
151 * Sets execution limits
153 * @param array $limits Associative array of limits. Keys (all optional):
154 * filesize (for ulimit -f), memory, time, walltime.
157 public function limits( array $limits ) {
158 if ( !isset( $limits['walltime'] ) && isset( $limits['time'] ) ) {
159 // Emulate the behavior of old wfShellExec() where walltime fell back on time
160 // if the latter was overridden and the former wasn't
161 $limits['walltime'] = $limits['time'];
163 $this->limits
= $limits +
$this->limits
;
169 * Sets environment variables which should be added to the executed command environment
171 * @param string[] $env array of variable name => value
174 public function environment( array $env ) {
181 * Sets calling function for profiler. By default, the caller for execute() will be used.
183 * @param string $method
186 public function profileMethod( $method ) {
187 $this->method
= $method;
193 * Controls whether stderr should be included in stdout, including errors from limit.sh.
194 * Default: don't include.
199 public function includeStderr( $yesno = true ) {
200 $this->doIncludeStderr
= $yesno;
206 * When enabled, text sent to stderr will be logged with a level of 'error'.
211 public function logStderr( $yesno = true ) {
212 $this->doLogStderr
= $yesno;
218 * Sets cgroup for this command
220 * @param string|false $cgroup Absolute file path to the cgroup, or false to not use a cgroup
223 public function cgroup( $cgroup ) {
224 $this->cgroup
= $cgroup;
230 * Set additional restrictions for this request
233 * @param int $restrictions
236 public function restrict( $restrictions ) {
237 $this->restrictions |
= $restrictions;
243 * Bitfield helper on whether a specific restriction is enabled
245 * @param int $restriction
249 protected function hasRestriction( $restriction ) {
250 return ( $this->restrictions
& $restriction ) === $restriction;
254 * If called, only the files/directories that are
255 * whitelisted will be available to the shell command.
257 * limit.sh will always be whitelisted
259 * @param string[] $paths
263 public function whitelistPaths( array $paths ) {
264 // Default implementation is a no-op
269 * String together all the options and build the final command
272 * @param string $command Already-escaped command to run
273 * @return array [ command, whether to use log pipe ]
275 protected function buildFinalCommand( $command ) {
277 foreach ( $this->env
as $k => $v ) {
278 if ( wfIsWindows() ) {
279 /* Surrounding a set in quotes (method used by wfEscapeShellArg) makes the quotes themselves
280 * appear in the environment variable, so we must use carat escaping as documented in
281 * https://technet.microsoft.com/en-us/library/cc723564.aspx
282 * Note however that the quote isn't listed there, but is needed, and the parentheses
283 * are listed there but doesn't appear to need it.
285 $envcmd .= "set $k=" . preg_replace( '/([&|()<>^"])/', '^\\1', $v ) . '&& ';
287 /* Assume this is a POSIX shell, thus required to accept variable assignments before the command
288 * http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_01
290 $envcmd .= "$k=" . escapeshellarg( $v ) . ' ';
295 $cmd = $envcmd . trim( $command );
297 if ( is_executable( '/bin/bash' ) ) {
298 $time = intval( $this->limits
['time'] );
299 $wallTime = intval( $this->limits
['walltime'] );
300 $mem = intval( $this->limits
['memory'] );
301 $filesize = intval( $this->limits
['filesize'] );
303 if ( $time > 0 ||
$mem > 0 ||
$filesize > 0 ||
$wallTime > 0 ) {
304 $cmd = '/bin/bash ' . escapeshellarg( __DIR__
. '/limit.sh' ) . ' ' .
305 escapeshellarg( $cmd ) . ' ' .
307 "MW_INCLUDE_STDERR=" . ( $this->doIncludeStderr ?
'1' : '' ) . ';' .
308 "MW_CPU_LIMIT=$time; " .
309 'MW_CGROUP=' . escapeshellarg( $this->cgroup
) . '; ' .
310 "MW_MEM_LIMIT=$mem; " .
311 "MW_FILE_SIZE_LIMIT=$filesize; " .
312 "MW_WALL_CLOCK_LIMIT=$wallTime; " .
313 "MW_USE_LOG_PIPE=yes"
318 if ( !$useLogPipe && $this->doIncludeStderr
) {
322 return [ $cmd, $useLogPipe ];
326 * Executes command. Afterwards, getExitCode() and getOutput() can be used to access execution
331 * @throws ProcOpenError
332 * @throws ShellDisabledError
334 public function execute() {
335 $this->everExecuted
= true;
337 $profileMethod = $this->method ?
: wfGetCaller();
339 list( $cmd, $useLogPipe ) = $this->buildFinalCommand( $this->command
);
341 $this->logger
->debug( __METHOD__
. ": $cmd" );
343 // Don't try to execute commands that exceed Linux's MAX_ARG_STRLEN.
344 // Other platforms may be more accomodating, but we don't want to be
345 // accomodating, because very long commands probably include user
346 // input. See T129506.
347 if ( strlen( $cmd ) > SHELL_MAX_ARG_STRLEN
) {
348 throw new Exception( __METHOD__
.
349 '(): total length of $cmd must not exceed SHELL_MAX_ARG_STRLEN' );
353 0 => [ 'file', 'php://stdin', 'r' ],
354 1 => [ 'pipe', 'w' ],
355 2 => [ 'pipe', 'w' ],
358 $desc[3] = [ 'pipe', 'w' ];
361 $scoped = Profiler
::instance()->scopedProfileIn( __FUNCTION__
. '-' . $profileMethod );
362 $proc = proc_open( $cmd, $desc, $pipes );
364 $this->logger
->error( "proc_open() failed: {command}", [ 'command' => $cmd ] );
365 throw new ProcOpenError();
367 $outBuffer = $logBuffer = '';
373 /* According to the documentation, it is possible for stream_select()
374 * to fail due to EINTR. I haven't managed to induce this in testing
375 * despite sending various signals. If it did happen, the error
376 * message would take the form:
378 * stream_select(): unable to select [4]: Interrupted system call (max_fd=5)
380 * where [4] is the value of the macro EINTR and "Interrupted system
381 * call" is string which according to the Linux manual is "possibly"
382 * localised according to LC_MESSAGES.
384 $eintr = defined( 'SOCKET_EINTR' ) ? SOCKET_EINTR
: 4;
385 $eintrMessage = "stream_select(): unable to select [$eintr]";
391 while ( $running === true ||
$numReadyPipes !== 0 ) {
393 $status = proc_get_status( $proc );
394 // If the process has terminated, switch to nonblocking selects
395 // for getting any data still waiting to be read.
396 if ( !$status['running'] ) {
402 $readyPipes = $pipes;
404 // clear get_last_error without actually raising an error
405 // from http://php.net/manual/en/function.error-get-last.php#113518
406 // TODO replace with clear_last_error when requirements are bumped to PHP7
407 set_error_handler( function () {
409 // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
410 @trigger_error
( '' );
411 restore_error_handler();
413 // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
414 $numReadyPipes = @stream_select
( $readyPipes, $emptyArray, $emptyArray, $timeout );
415 if ( $numReadyPipes === false ) {
416 $error = error_get_last();
417 if ( strncmp( $error['message'], $eintrMessage, strlen( $eintrMessage ) ) == 0 ) {
420 trigger_error( $error['message'], E_USER_WARNING
);
421 $logMsg = $error['message'];
425 foreach ( $readyPipes as $fd => $pipe ) {
426 $block = fread( $pipe, 65536 );
427 if ( $block === '' ) {
429 fclose( $pipes[$fd] );
430 unset( $pipes[$fd] );
434 } elseif ( $block === false ) {
436 $logMsg = "Error reading from pipe";
438 } elseif ( $fd == 1 ) {
440 $outBuffer .= $block;
441 } elseif ( $fd == 2 ) {
443 $errBuffer .= $block;
444 } elseif ( $fd == 3 ) {
446 $logBuffer .= $block;
447 if ( strpos( $block, "\n" ) !== false ) {
448 $lines = explode( "\n", $logBuffer );
449 $logBuffer = array_pop( $lines );
450 foreach ( $lines as $line ) {
451 $this->logger
->info( $line );
458 foreach ( $pipes as $pipe ) {
462 // Use the status previously collected if possible, since proc_get_status()
463 // just calls waitpid() which will not return anything useful the second time.
465 $status = proc_get_status( $proc );
468 if ( $logMsg !== false ) {
472 } elseif ( $status['signaled'] ) {
473 $logMsg = "Exited with signal {$status['termsig']}";
474 $retval = 128 +
$status['termsig'];
477 if ( $status['running'] ) {
478 $retval = proc_close( $proc );
480 $retval = $status['exitcode'];
483 if ( $retval == 127 ) {
484 $logMsg = "Possibly missing executable file";
485 } elseif ( $retval >= 129 && $retval <= 192 ) {
486 $logMsg = "Probably exited with signal " . ( $retval - 128 );
490 if ( $logMsg !== false ) {
491 $this->logger
->warning( "$logMsg: {command}", [ 'command' => $cmd ] );
494 if ( $errBuffer && $this->doLogStderr
) {
495 $this->logger
->error( "Error running {command}: {error}", [
497 'error' => $errBuffer,
498 'exitcode' => $retval,
499 'exception' => new Exception( 'Shell error' ),
503 return new Result( $retval, $outBuffer, $errBuffer );