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
;
29 use Wikimedia\AtEase\AtEase
;
32 * Class used for executing shell commands
40 protected $command = '';
60 /** @var string|null */
64 private $doIncludeStderr = false;
67 private $doLogStderr = false;
70 private $everExecuted = false;
72 /** @var string|false */
73 private $cgroup = false;
76 * Bitfield with restrictions
80 protected $restrictions = 0;
83 * Don't call directly, instead use Shell::command()
85 * @throws ShellDisabledError
87 public function __construct() {
88 if ( Shell
::isDisabled() ) {
89 throw new ShellDisabledError();
92 $this->setLogger( new NullLogger() );
96 * Makes sure the programmer didn't forget to execute the command after all
98 public function __destruct() {
99 if ( !$this->everExecuted
) {
100 $context = [ 'command' => $this->command
];
101 $message = __CLASS__
. " was instantiated, but execute() was never called.";
102 if ( $this->method
) {
103 $message .= ' Calling method: {method}.';
104 $context['method'] = $this->method
;
106 $message .= ' Command: {command}';
107 $this->logger
->warning( $message, $context );
112 * Adds parameters to the command. All parameters are sanitized via Shell::escape().
113 * Null values are ignored.
115 * @param string|string[] ...$args
118 public function params( ...$args ): Command
{
119 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
120 // If only one argument has been passed, and that argument is an array,
121 // treat it as a list of arguments
122 $args = reset( $args );
124 $this->command
= trim( $this->command
. ' ' . Shell
::escape( $args ) );
130 * Adds unsafe parameters to the command. These parameters are NOT sanitized in any way.
131 * Null values are ignored.
133 * @param string|string[] ...$args
136 public function unsafeParams( ...$args ): Command
{
137 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
138 // If only one argument has been passed, and that argument is an array,
139 // treat it as a list of arguments
140 $args = reset( $args );
142 $args = array_filter( $args,
143 function ( $value ) {
144 return $value !== null;
147 $this->command
= trim( $this->command
. ' ' . implode( ' ', $args ) );
153 * Sets execution limits
155 * @param array $limits Associative array of limits. Keys (all optional):
156 * filesize (for ulimit -f), memory, time, walltime.
159 public function limits( array $limits ): Command
{
160 if ( !isset( $limits['walltime'] ) && isset( $limits['time'] ) ) {
161 // Emulate the behavior of old wfShellExec() where walltime fell back on time
162 // if the latter was overridden and the former wasn't
163 $limits['walltime'] = $limits['time'];
165 $this->limits
= $limits +
$this->limits
;
171 * Sets environment variables which should be added to the executed command environment
173 * @param string[] $env array of variable name => value
176 public function environment( array $env ): Command
{
183 * Sets calling function for profiler. By default, the caller for execute() will be used.
185 * @param string $method
188 public function profileMethod( $method ): Command
{
189 $this->method
= $method;
195 * Sends the provided input to the command.
196 * When set to null (default), the command will use the standard input.
197 * @param string|null $inputString
200 public function input( $inputString ): Command
{
201 $this->inputString
= is_null( $inputString ) ?
null : (string)$inputString;
207 * Controls whether stderr should be included in stdout, including errors from limit.sh.
208 * Default: don't include.
213 public function includeStderr( $yesno = true ): Command
{
214 $this->doIncludeStderr
= $yesno;
220 * When enabled, text sent to stderr will be logged with a level of 'error'.
225 public function logStderr( $yesno = true ): Command
{
226 $this->doLogStderr
= $yesno;
232 * Sets cgroup for this command
234 * @param string|false $cgroup Absolute file path to the cgroup, or false to not use a cgroup
237 public function cgroup( $cgroup ): Command
{
238 $this->cgroup
= $cgroup;
244 * Set additional restrictions for this request
247 * @param int $restrictions
250 public function restrict( $restrictions ): Command
{
251 $this->restrictions |
= $restrictions;
257 * Bitfield helper on whether a specific restriction is enabled
259 * @param int $restriction
263 protected function hasRestriction( $restriction ) {
264 return ( $this->restrictions
& $restriction ) === $restriction;
268 * If called, only the files/directories that are
269 * whitelisted will be available to the shell command.
271 * limit.sh will always be whitelisted
273 * @param string[] $paths
277 public function whitelistPaths( array $paths ): Command
{
278 // Default implementation is a no-op
283 * String together all the options and build the final command
286 * @param string $command Already-escaped command to run
287 * @return array [ command, whether to use log pipe ]
289 protected function buildFinalCommand( $command ) {
291 foreach ( $this->env
as $k => $v ) {
292 if ( wfIsWindows() ) {
293 /* Surrounding a set in quotes (method used by wfEscapeShellArg) makes the quotes themselves
294 * appear in the environment variable, so we must use carat escaping as documented in
295 * https://technet.microsoft.com/en-us/library/cc723564.aspx
296 * Note however that the quote isn't listed there, but is needed, and the parentheses
297 * are listed there but doesn't appear to need it.
299 $envcmd .= "set $k=" . preg_replace( '/([&|()<>^"])/', '^\\1', $v ) . '&& ';
301 /* Assume this is a POSIX shell, thus required to accept variable assignments before the command
302 * http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_01
304 $envcmd .= "$k=" . escapeshellarg( $v ) . ' ';
309 $cmd = $envcmd . trim( $command );
311 if ( is_executable( '/bin/bash' ) ) {
312 $time = intval( $this->limits
['time'] );
313 $wallTime = intval( $this->limits
['walltime'] );
314 $mem = intval( $this->limits
['memory'] );
315 $filesize = intval( $this->limits
['filesize'] );
317 if ( $time > 0 ||
$mem > 0 ||
$filesize > 0 ||
$wallTime > 0 ) {
318 $cmd = '/bin/bash ' . escapeshellarg( __DIR__
. '/limit.sh' ) . ' ' .
319 escapeshellarg( $cmd ) . ' ' .
321 "MW_INCLUDE_STDERR=" . ( $this->doIncludeStderr ?
'1' : '' ) . ';' .
322 "MW_CPU_LIMIT=$time; " .
323 'MW_CGROUP=' . escapeshellarg( $this->cgroup
) . '; ' .
324 "MW_MEM_LIMIT=$mem; " .
325 "MW_FILE_SIZE_LIMIT=$filesize; " .
326 "MW_WALL_CLOCK_LIMIT=$wallTime; " .
327 "MW_USE_LOG_PIPE=yes"
332 if ( !$useLogPipe && $this->doIncludeStderr
) {
336 return [ $cmd, $useLogPipe ];
340 * Executes command. Afterwards, getExitCode() and getOutput() can be used to access execution
345 * @throws ProcOpenError
346 * @throws ShellDisabledError
348 public function execute() {
349 $this->everExecuted
= true;
351 $profileMethod = $this->method ?
: wfGetCaller();
353 list( $cmd, $useLogPipe ) = $this->buildFinalCommand( $this->command
);
355 $this->logger
->debug( __METHOD__
. ": $cmd" );
357 // Don't try to execute commands that exceed Linux's MAX_ARG_STRLEN.
358 // Other platforms may be more accomodating, but we don't want to be
359 // accomodating, because very long commands probably include user
360 // input. See T129506.
361 if ( strlen( $cmd ) > SHELL_MAX_ARG_STRLEN
) {
362 throw new Exception( __METHOD__
.
363 '(): total length of $cmd must not exceed SHELL_MAX_ARG_STRLEN' );
367 0 => $this->inputString
=== null ?
[ 'file', 'php://stdin', 'r' ] : [ 'pipe', 'r' ],
368 1 => [ 'pipe', 'w' ],
369 2 => [ 'pipe', 'w' ],
372 $desc[3] = [ 'pipe', 'w' ];
375 $scoped = Profiler
::instance()->scopedProfileIn( __FUNCTION__
. '-' . $profileMethod );
376 $proc = proc_open( $cmd, $desc, $pipes );
378 $this->logger
->error( "proc_open() failed: {command}", [ 'command' => $cmd ] );
379 throw new ProcOpenError();
383 0 => $this->inputString
, // input
392 /* According to the documentation, it is possible for stream_select()
393 * to fail due to EINTR. I haven't managed to induce this in testing
394 * despite sending various signals. If it did happen, the error
395 * message would take the form:
397 * stream_select(): unable to select [4]: Interrupted system call (max_fd=5)
399 * where [4] is the value of the macro EINTR and "Interrupted system
400 * call" is string which according to the Linux manual is "possibly"
401 * localised according to LC_MESSAGES.
403 $eintr = defined( 'SOCKET_EINTR' ) ? SOCKET_EINTR
: 4;
404 $eintrMessage = "stream_select(): unable to select [$eintr]";
406 /* The select(2) system call only guarantees a "sufficiently small write"
407 * can be made without blocking. And on Linux the read might block too
408 * in certain cases, although I don't know if any of them can occur here.
409 * Regardless, set all the pipes to non-blocking to avoid T184171.
411 foreach ( $pipes as $pipe ) {
412 stream_set_blocking( $pipe, false );
419 while ( $pipes && ( $running === true ||
$numReadyPipes !== 0 ) ) {
421 $status = proc_get_status( $proc );
422 // If the process has terminated, switch to nonblocking selects
423 // for getting any data still waiting to be read.
424 if ( !$status['running'] ) {
430 // clear get_last_error without actually raising an error
431 // from https://www.php.net/manual/en/function.error-get-last.php#113518
432 // TODO replace with clear_last_error when requirements are bumped to PHP7
433 set_error_handler( function () {
435 AtEase
::suppressWarnings();
437 AtEase
::restoreWarnings();
438 restore_error_handler();
440 $readPipes = array_filter( $pipes, function ( $fd ) use ( $desc ) {
441 return $desc[$fd][0] === 'pipe' && $desc[$fd][1] === 'r';
442 }, ARRAY_FILTER_USE_KEY
);
443 $writePipes = array_filter( $pipes, function ( $fd ) use ( $desc ) {
444 return $desc[$fd][0] === 'pipe' && $desc[$fd][1] === 'w';
445 }, ARRAY_FILTER_USE_KEY
);
446 // stream_select parameter names are from the POV of us being able to do the operation;
447 // proc_open desriptor types are from the POV of the process doing it.
448 // So $writePipes is passed as the $read parameter and $readPipes as $write.
449 AtEase
::suppressWarnings();
450 $numReadyPipes = stream_select( $writePipes, $readPipes, $emptyArray, $timeout );
451 AtEase
::restoreWarnings();
452 if ( $numReadyPipes === false ) {
453 $error = error_get_last();
454 if ( strncmp( $error['message'], $eintrMessage, strlen( $eintrMessage ) ) == 0 ) {
457 trigger_error( $error['message'], E_USER_WARNING
);
458 $logMsg = $error['message'];
462 foreach ( $writePipes +
$readPipes as $fd => $pipe ) {
463 // True if a pipe is unblocked for us to write into, false if for reading from
464 $isWrite = array_key_exists( $fd, $readPipes );
467 // Don't bother writing if the buffer is empty
468 if ( $buffers[$fd] === '' ) {
469 fclose( $pipes[$fd] );
470 unset( $pipes[$fd] );
473 $res = fwrite( $pipe, $buffers[$fd], 65536 );
475 $res = fread( $pipe, 65536 );
478 if ( $res === false ) {
479 $logMsg = 'Error ' . ( $isWrite ?
'writing to' : 'reading from' ) . ' pipe';
483 if ( $res === '' ||
$res === 0 ) {
485 if ( feof( $pipe ) ) {
486 fclose( $pipes[$fd] );
487 unset( $pipes[$fd] );
489 } elseif ( $isWrite ) {
490 $buffers[$fd] = (string)substr( $buffers[$fd], $res );
491 if ( $buffers[$fd] === '' ) {
492 fclose( $pipes[$fd] );
493 unset( $pipes[$fd] );
496 $buffers[$fd] .= $res;
497 if ( $fd === 3 && strpos( $res, "\n" ) !== false ) {
498 // For the log FD, every line is a separate log entry.
499 $lines = explode( "\n", $buffers[3] );
500 $buffers[3] = array_pop( $lines );
501 foreach ( $lines as $line ) {
502 $this->logger
->info( $line );
509 foreach ( $pipes as $pipe ) {
513 // Use the status previously collected if possible, since proc_get_status()
514 // just calls waitpid() which will not return anything useful the second time.
516 $status = proc_get_status( $proc );
519 if ( $logMsg !== false ) {
523 } elseif ( $status['signaled'] ) {
524 $logMsg = "Exited with signal {$status['termsig']}";
525 $retval = 128 +
$status['termsig'];
528 if ( $status['running'] ) {
529 $retval = proc_close( $proc );
531 $retval = $status['exitcode'];
534 if ( $retval == 127 ) {
535 $logMsg = "Possibly missing executable file";
536 } elseif ( $retval >= 129 && $retval <= 192 ) {
537 $logMsg = "Probably exited with signal " . ( $retval - 128 );
541 if ( $logMsg !== false ) {
542 $this->logger
->warning( "$logMsg: {command}", [ 'command' => $cmd ] );
545 if ( $buffers[2] && $this->doLogStderr
) {
546 $this->logger
->error( "Error running {command}: {error}", [
548 'error' => $buffers[2],
549 'exitcode' => $retval,
550 'exception' => new Exception( 'Shell error' ),
554 return new Result( $retval, $buffers[1], $buffers[2] );
558 * Returns the final command line before environment/limiting, etc are applied.
559 * Use string conversion only for debugging, don't try to pass this to
560 * some other execution medium.
564 public function __toString() {
565 return "#Command: {$this->command}";