MediaWiki  master
Command.php
Go to the documentation of this file.
1 <?php
21 namespace MediaWiki\Shell;
22 
23 use Exception;
26 use Profiler;
27 use Psr\Log\LoggerAwareTrait;
28 use Psr\Log\NullLogger;
29 use Wikimedia\AtEase\AtEase;
30 
36 class Command {
37  use LoggerAwareTrait;
38 
40  protected $command = '';
41 
43  private $limits = [
44  // seconds
45  'time' => 180,
46  // seconds
47  'walltime' => 180,
48  // KB
49  'memory' => 307200,
50  // KB
51  'filesize' => 102400,
52  ];
53 
55  private $env = [];
56 
58  private $method;
59 
61  private $inputString;
62 
64  private $doIncludeStderr = false;
65 
67  private $doLogStderr = false;
68 
70  private $everExecuted = false;
71 
73  private $cgroup = false;
74 
80  protected $restrictions = 0;
81 
87  public function __construct() {
88  if ( Shell::isDisabled() ) {
89  throw new ShellDisabledError();
90  }
91 
92  $this->setLogger( new NullLogger() );
93  }
94 
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;
105  }
106  $message .= ' Command: {command}';
107  $this->logger->warning( $message, $context );
108  }
109  }
110 
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 );
123  }
124  $this->command = trim( $this->command . ' ' . Shell::escape( $args ) );
125 
126  return $this;
127  }
128 
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 );
141  }
142  $args = array_filter( $args,
143  function ( $value ) {
144  return $value !== null;
145  }
146  );
147  $this->command = trim( $this->command . ' ' . implode( ' ', $args ) );
148 
149  return $this;
150  }
151 
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'];
164  }
165  $this->limits = $limits + $this->limits;
166 
167  return $this;
168  }
169 
176  public function environment( array $env ): Command {
177  $this->env = $env;
178 
179  return $this;
180  }
181 
188  public function profileMethod( string $method ): Command {
189  $this->method = $method;
190 
191  return $this;
192  }
193 
200  public function input( ?string $inputString ): Command {
201  $this->inputString = $inputString;
202 
203  return $this;
204  }
205 
213  public function includeStderr( bool $yesno = true ): Command {
214  $this->doIncludeStderr = $yesno;
215 
216  return $this;
217  }
218 
225  public function logStderr( bool $yesno = true ): Command {
226  $this->doLogStderr = $yesno;
227 
228  return $this;
229  }
230 
237  public function cgroup( $cgroup ): Command {
238  $this->cgroup = $cgroup;
239 
240  return $this;
241  }
242 
265  public function restrict( int $restrictions ): Command {
266  $this->restrictions = $restrictions;
267 
268  return $this;
269  }
270 
278  protected function hasRestriction( int $restriction ): bool {
279  return ( $this->restrictions & $restriction ) === $restriction;
280  }
281 
292  public function whitelistPaths( array $paths ): Command {
293  // Default implementation is a no-op
294  return $this;
295  }
296 
304  protected function buildFinalCommand( string $command ): array {
305  $envcmd = '';
306  foreach ( $this->env as $k => $v ) {
307  if ( wfIsWindows() ) {
308  /* Surrounding a set in quotes (method used by wfEscapeShellArg) makes the quotes themselves
309  * appear in the environment variable, so we must use carat escaping as documented in
310  * https://technet.microsoft.com/en-us/library/cc723564.aspx
311  * Note however that the quote isn't listed there, but is needed, and the parentheses
312  * are listed there but doesn't appear to need it.
313  */
314  $envcmd .= "set $k=" . preg_replace( '/([&|()<>^"])/', '^\\1', $v ) . '&& ';
315  } else {
316  /* Assume this is a POSIX shell, thus required to accept variable assignments before the command
317  * http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_01
318  */
319  $envcmd .= "$k=" . escapeshellarg( $v ) . ' ';
320  }
321  }
322 
323  $useLogPipe = false;
324  $cmd = $envcmd . trim( $command );
325 
326  if ( is_executable( '/bin/bash' ) ) {
327  $time = intval( $this->limits['time'] );
328  $wallTime = intval( $this->limits['walltime'] );
329  $mem = intval( $this->limits['memory'] );
330  $filesize = intval( $this->limits['filesize'] );
331 
332  if ( $time > 0 || $mem > 0 || $filesize > 0 || $wallTime > 0 ) {
333  $cmd = '/bin/bash ' . escapeshellarg( __DIR__ . '/limit.sh' ) . ' ' .
334  escapeshellarg( $cmd ) . ' ' .
335  escapeshellarg(
336  "MW_INCLUDE_STDERR=" . ( $this->doIncludeStderr ? '1' : '' ) . ';' .
337  "MW_CPU_LIMIT=$time; " .
338  'MW_CGROUP=' . escapeshellarg( $this->cgroup ) . '; ' .
339  "MW_MEM_LIMIT=$mem; " .
340  "MW_FILE_SIZE_LIMIT=$filesize; " .
341  "MW_WALL_CLOCK_LIMIT=$wallTime; " .
342  "MW_USE_LOG_PIPE=yes"
343  );
344  $useLogPipe = true;
345  }
346  }
347  if ( !$useLogPipe && $this->doIncludeStderr ) {
348  $cmd .= ' 2>&1';
349  }
350 
351  return [ $cmd, $useLogPipe ];
352  }
353 
363  public function execute(): Result {
364  $this->everExecuted = true;
365 
366  $profileMethod = $this->method ?: wfGetCaller();
367 
368  list( $cmd, $useLogPipe ) = $this->buildFinalCommand( $this->command );
369 
370  $this->logger->debug( __METHOD__ . ": $cmd" );
371 
372  // Don't try to execute commands that exceed Linux's MAX_ARG_STRLEN.
373  // Other platforms may be more accomodating, but we don't want to be
374  // accomodating, because very long commands probably include user
375  // input. See T129506.
376  if ( strlen( $cmd ) > SHELL_MAX_ARG_STRLEN ) {
377  throw new Exception( __METHOD__ .
378  '(): total length of $cmd must not exceed SHELL_MAX_ARG_STRLEN' );
379  }
380 
381  $desc = [
382  0 => $this->inputString === null ? [ 'file', 'php://stdin', 'r' ] : [ 'pipe', 'r' ],
383  1 => [ 'pipe', 'w' ],
384  2 => [ 'pipe', 'w' ],
385  ];
386  if ( $useLogPipe ) {
387  $desc[3] = [ 'pipe', 'w' ];
388  }
389  $pipes = null;
390  $scoped = Profiler::instance()->scopedProfileIn( __FUNCTION__ . '-' . $profileMethod );
391  $proc = proc_open( $cmd, $desc, $pipes );
392  if ( !$proc ) {
393  $this->logger->error( "proc_open() failed: {command}", [ 'command' => $cmd ] );
394  throw new ProcOpenError();
395  }
396 
397  $buffers = [
398  0 => $this->inputString, // input
399  1 => '', // stdout
400  2 => null, // stderr
401  3 => '', // log
402  ];
403  $emptyArray = [];
404  $status = false;
405  $logMsg = false;
406 
407  /* According to the documentation, it is possible for stream_select()
408  * to fail due to EINTR. I haven't managed to induce this in testing
409  * despite sending various signals. If it did happen, the error
410  * message would take the form:
411  *
412  * stream_select(): unable to select [4]: Interrupted system call (max_fd=5)
413  *
414  * where [4] is the value of the macro EINTR and "Interrupted system
415  * call" is string which according to the Linux manual is "possibly"
416  * localised according to LC_MESSAGES.
417  */
418  $eintr = defined( 'SOCKET_EINTR' ) ? SOCKET_EINTR : 4;
419  $eintrMessage = "stream_select(): unable to select [$eintr]";
420 
421  /* The select(2) system call only guarantees a "sufficiently small write"
422  * can be made without blocking. And on Linux the read might block too
423  * in certain cases, although I don't know if any of them can occur here.
424  * Regardless, set all the pipes to non-blocking to avoid T184171.
425  */
426  foreach ( $pipes as $pipe ) {
427  stream_set_blocking( $pipe, false );
428  }
429 
430  $running = true;
431  $timeout = null;
432  $numReadyPipes = 0;
433 
434  while ( $pipes && ( $running === true || $numReadyPipes !== 0 ) ) {
435  if ( $running ) {
436  $status = proc_get_status( $proc );
437  // If the process has terminated, switch to nonblocking selects
438  // for getting any data still waiting to be read.
439  if ( !$status['running'] ) {
440  $running = false;
441  $timeout = 0;
442  }
443  }
444 
445  error_clear_last();
446 
447  $readPipes = array_filter( $pipes, function ( $fd ) use ( $desc ) {
448  return $desc[$fd][0] === 'pipe' && $desc[$fd][1] === 'r';
449  }, ARRAY_FILTER_USE_KEY );
450  $writePipes = array_filter( $pipes, function ( $fd ) use ( $desc ) {
451  return $desc[$fd][0] === 'pipe' && $desc[$fd][1] === 'w';
452  }, ARRAY_FILTER_USE_KEY );
453  // stream_select parameter names are from the POV of us being able to do the operation;
454  // proc_open desriptor types are from the POV of the process doing it.
455  // So $writePipes is passed as the $read parameter and $readPipes as $write.
456  AtEase::suppressWarnings();
457  $numReadyPipes = stream_select( $writePipes, $readPipes, $emptyArray, $timeout );
458  AtEase::restoreWarnings();
459  if ( $numReadyPipes === false ) {
460  $error = error_get_last();
461  if ( strncmp( $error['message'], $eintrMessage, strlen( $eintrMessage ) ) == 0 ) {
462  continue;
463  } else {
464  trigger_error( $error['message'], E_USER_WARNING );
465  $logMsg = $error['message'];
466  break;
467  }
468  }
469  foreach ( $writePipes + $readPipes as $fd => $pipe ) {
470  // True if a pipe is unblocked for us to write into, false if for reading from
471  $isWrite = array_key_exists( $fd, $readPipes );
472 
473  if ( $isWrite ) {
474  // Don't bother writing if the buffer is empty
475  if ( $buffers[$fd] === '' ) {
476  fclose( $pipes[$fd] );
477  unset( $pipes[$fd] );
478  continue;
479  }
480  $res = fwrite( $pipe, $buffers[$fd], 65536 );
481  } else {
482  $res = fread( $pipe, 65536 );
483  }
484 
485  if ( $res === false ) {
486  $logMsg = 'Error ' . ( $isWrite ? 'writing to' : 'reading from' ) . ' pipe';
487  break 2;
488  }
489 
490  if ( $res === '' || $res === 0 ) {
491  // End of file?
492  if ( feof( $pipe ) ) {
493  fclose( $pipes[$fd] );
494  unset( $pipes[$fd] );
495  }
496  } elseif ( $isWrite ) {
497  $buffers[$fd] = (string)substr( $buffers[$fd], $res );
498  if ( $buffers[$fd] === '' ) {
499  fclose( $pipes[$fd] );
500  unset( $pipes[$fd] );
501  }
502  } else {
503  $buffers[$fd] .= $res;
504  if ( $fd === 3 && strpos( $res, "\n" ) !== false ) {
505  // For the log FD, every line is a separate log entry.
506  $lines = explode( "\n", $buffers[3] );
507  $buffers[3] = array_pop( $lines );
508  foreach ( $lines as $line ) {
509  $this->logger->info( $line );
510  }
511  }
512  }
513  }
514  }
515 
516  foreach ( $pipes as $pipe ) {
517  fclose( $pipe );
518  }
519 
520  // Use the status previously collected if possible, since proc_get_status()
521  // just calls waitpid() which will not return anything useful the second time.
522  if ( $running ) {
523  $status = proc_get_status( $proc );
524  }
525 
526  if ( $logMsg !== false ) {
527  // Read/select error
528  $retval = -1;
529  proc_close( $proc );
530  } elseif ( $status['signaled'] ) {
531  $logMsg = "Exited with signal {$status['termsig']}";
532  $retval = 128 + $status['termsig'];
533  proc_close( $proc );
534  } else {
535  if ( $status['running'] ) {
536  $retval = proc_close( $proc );
537  } else {
538  $retval = $status['exitcode'];
539  proc_close( $proc );
540  }
541  if ( $retval == 127 ) {
542  $logMsg = "Possibly missing executable file";
543  } elseif ( $retval >= 129 && $retval <= 192 ) {
544  $logMsg = "Probably exited with signal " . ( $retval - 128 );
545  }
546  }
547 
548  if ( $logMsg !== false ) {
549  $this->logger->warning( "$logMsg: {command}", [ 'command' => $cmd ] );
550  }
551 
552  // @phan-suppress-next-line PhanImpossibleCondition
553  if ( $buffers[2] && $this->doLogStderr ) {
554  $this->logger->error( "Error running {command}: {error}", [
555  'command' => $cmd,
556  'error' => $buffers[2],
557  'exitcode' => $retval,
558  'exception' => new Exception( 'Shell error' ),
559  ] );
560  }
561 
562  return new Result( $retval, $buffers[1], $buffers[2] );
563  }
564 
572  public function __toString(): string {
573  return "#Command: {$this->command}";
574  }
575 }
MediaWiki\Shell\Command\$everExecuted
bool $everExecuted
Definition: Command.php:70
MediaWiki\Shell\Result
Returned by MediaWiki\Shell\Command::execute()
Definition: Result.php:30
MediaWiki\Shell\Command\$doIncludeStderr
bool $doIncludeStderr
Definition: Command.php:64
MediaWiki\Shell\Command\__destruct
__destruct()
Makes sure the programmer didn't forget to execute the command after all.
Definition: Command.php:98
MediaWiki\Shell\Command\unsafeParams
unsafeParams(... $args)
Adds unsafe parameters to the command.
Definition: Command.php:136
MediaWiki\ProcOpenError
@newable
Definition: ProcOpenError.php:28
MediaWiki\Shell\Command\buildFinalCommand
buildFinalCommand(string $command)
String together all the options and build the final command to execute.
Definition: Command.php:304
Profiler\instance
static instance()
Singleton.
Definition: Profiler.php:63
MediaWiki\Shell\Command
Class used for executing shell commands.
Definition: Command.php:36
MediaWiki\Shell\Command\$inputString
string null $inputString
Definition: Command.php:61
MediaWiki\Shell\Command\cgroup
cgroup( $cgroup)
Sets cgroup for this command.
Definition: Command.php:237
MediaWiki\Shell\Command\limits
limits(array $limits)
Sets execution limits.
Definition: Command.php:159
MediaWiki\Shell\Command\$restrictions
int $restrictions
Bitfield with restrictions.
Definition: Command.php:80
$res
$res
Definition: testCompression.php:57
MediaWiki\Shell\Command\logStderr
logStderr(bool $yesno=true)
When enabled, text sent to stderr will be logged with a level of 'error'.
Definition: Command.php:225
MediaWiki\Shell\Command\includeStderr
includeStderr(bool $yesno=true)
Controls whether stderr should be included in stdout, including errors from limit....
Definition: Command.php:213
Profiler
Profiler base class that defines the interface and some shared functionality.
Definition: Profiler.php:33
SHELL_MAX_ARG_STRLEN
const SHELL_MAX_ARG_STRLEN
Definition: Defines.php:260
$args
if( $line===false) $args
Definition: mcc.php:124
MediaWiki\Shell\Command\$env
string[] $env
Definition: Command.php:55
MediaWiki\Shell\Command\__toString
__toString()
Returns the final command line before environment/limiting, etc are applied.
Definition: Command.php:572
MediaWiki\Shell\Command\environment
environment(array $env)
Sets environment variables which should be added to the executed command environment.
Definition: Command.php:176
MediaWiki\Shell\Shell\isDisabled
static isDisabled()
Check if this class is effectively disabled via php.ini config.
Definition: Shell.php:137
MediaWiki\Shell\Command\profileMethod
profileMethod(string $method)
Sets calling function for profiler.
Definition: Command.php:188
MediaWiki\Shell\Command\$command
string $command
Definition: Command.php:40
MediaWiki\Shell\Command\$doLogStderr
bool $doLogStderr
Definition: Command.php:67
wfIsWindows
wfIsWindows()
Check if the operating system is Windows.
Definition: GlobalFunctions.php:1846
MediaWiki\Shell\Command\hasRestriction
hasRestriction(int $restriction)
Bitfield helper on whether a specific restriction is enabled.
Definition: Command.php:278
$line
$line
Definition: mcc.php:119
MediaWiki\ShellDisabledError
@newable
Definition: ShellDisabledError.php:29
MediaWiki\Shell\Shell\escape
static escape(... $args)
Version of escapeshellarg() that works better on Windows.
Definition: Shell.php:163
$lines
if(!file_exists( $CREDITS)) $lines
Definition: updateCredits.php:49
MediaWiki\Shell
Copyright (C) 2017 Kunal Mehta legoktm@member.fsf.org
Definition: Command.php:21
MediaWiki\Shell\Command\$limits
array $limits
Definition: Command.php:43
MediaWiki\Shell\Command\restrict
restrict(int $restrictions)
Set restrictions for this request, overwriting any previously set restrictions.
Definition: Command.php:265
MediaWiki\Shell\Command\$cgroup
string false $cgroup
Definition: Command.php:73
MediaWiki\Shell\Command\$method
string $method
Definition: Command.php:58
MediaWiki\$context
IContextSource $context
Definition: MediaWiki.php:40
MediaWiki\Shell\Command\whitelistPaths
whitelistPaths(array $paths)
If called, only the files/directories that are whitelisted will be available to the shell command.
Definition: Command.php:292
MediaWiki\Shell\Command\input
input(?string $inputString)
Sends the provided input to the command.
Definition: Command.php:200
MediaWiki\Shell\Command\execute
execute()
Executes command.
Definition: Command.php:363
wfGetCaller
wfGetCaller( $level=2)
Get the name of the function which called this function wfGetCaller( 1 ) is the function with the wfG...
Definition: GlobalFunctions.php:1390
MediaWiki\Shell\Command\__construct
__construct()
Don't call directly, instead use Shell::command()
Definition: Command.php:87
MediaWiki\Shell\Command\params
params(... $args)
Adds parameters to the command.
Definition: Command.php:118