includes/shell/Command.php

   1 <?php
   2 /**
   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.
   7  *
   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.
  12  *
  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
  17  *
  18  * @file
  19  */
  20
  21 namespace MediaWiki\Shell;
  22
  23 use Exception;
  24 use MediaWiki\ProcOpenError;
  25 use MediaWiki\ShellDisabledError;
  26 use Profiler;
  27 use Psr\Log\LoggerAwareTrait;
  28 use Psr\Log\NullLogger;
  29
  30 /**
  31  * Class used for executing shell commands
  32  *
  33  * @since 1.30
  34  */
  35 class Command {
  36         use LoggerAwareTrait;
  37
  38         /** @var string */
  39         protected $command = '';
  40
  41         /** @var array */
  42         private $limits = [
  43                 // seconds
  44                 'time' => 180,
  45                 // seconds
  46                 'walltime' => 180,
  47                 // KB
  48                 'memory' => 307200,
  49                 // KB
  50                 'filesize' => 102400,
  51         ];
  52
  53         /** @var string[] */
  54         private $env = [];
  55
  56         /** @var string */
  57         private $method;
  58
  59         /** @var bool */
  60         private $doIncludeStderr = false;
  61
  62         /** @var bool */
  63         private $doLogStderr = false;
  64
  65         /** @var bool */
  66         private $everExecuted = false;
  67
  68         /** @var string|false */
  69         private $cgroup = false;
  70
  71         /**
  72          * bitfield with restrictions
  73          *
  74          * @var int
  75          */
  76         protected $restrictions = 0;
  77
  78         /**
  79          * Constructor. Don't call directly, instead use Shell::command()
  80          *
  81          * @throws ShellDisabledError
  82          */
  83         public function __construct() {
  84                 if ( Shell::isDisabled() ) {
  85                         throw new ShellDisabledError();
  86                 }
  87
  88                 $this->setLogger( new NullLogger() );
  89         }
  90
  91         /**
  92          * Destructor. Makes sure programmer didn't forget to execute the command after all
  93          */
  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;
 101                         }
 102                         $message .= ' Command: {command}';
 103                         $this->logger->warning( $message, $context );
 104                 }
 105         }
 106
 107         /**
 108          * Adds parameters to the command. All parameters are sanitized via Shell::escape().
 109          * Null values are ignored.
 110          *
 111          * @param string|string[] $args,...
 112          * @return $this
 113          */
 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 );
 120                 }
 121                 $this->command = trim( $this->command . ' ' . Shell::escape( $args ) );
 122
 123                 return $this;
 124         }
 125
 126         /**
 127          * Adds unsafe parameters to the command. These parameters are NOT sanitized in any way.
 128          * Null values are ignored.
 129          *
 130          * @param string|string[] $args,...
 131          * @return $this
 132          */
 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 );
 139                 }
 140                 $args = array_filter( $args,
 141                         function ( $value ) {
 142                                 return $value !== null;
 143                         }
 144                 );
 145                 $this->command = trim( $this->command . ' ' . implode( ' ', $args ) );
 146
 147                 return $this;
 148         }
 149
 150         /**
 151          * Sets execution limits
 152          *
 153          * @param array $limits Associative array of limits. Keys (all optional):
 154          *   filesize (for ulimit -f), memory, time, walltime.
 155          * @return $this
 156          */
 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'];
 162                 }
 163                 $this->limits = $limits + $this->limits;
 164
 165                 return $this;
 166         }
 167
 168         /**
 169          * Sets environment variables which should be added to the executed command environment
 170          *
 171          * @param string[] $env array of variable name => value
 172          * @return $this
 173          */
 174         public function environment( array $env ) {
 175                 $this->env = $env;
 176
 177                 return $this;
 178         }
 179
 180         /**
 181          * Sets calling function for profiler. By default, the caller for execute() will be used.
 182          *
 183          * @param string $method
 184          * @return $this
 185          */
 186         public function profileMethod( $method ) {
 187                 $this->method = $method;
 188
 189                 return $this;
 190         }
 191
 192         /**
 193          * Controls whether stderr should be included in stdout, including errors from limit.sh.
 194          * Default: don't include.
 195          *
 196          * @param bool $yesno
 197          * @return $this
 198          */
 199         public function includeStderr( $yesno = true ) {
 200                 $this->doIncludeStderr = $yesno;
 201
 202                 return $this;
 203         }
 204
 205         /**
 206          * When enabled, text sent to stderr will be logged with a level of 'error'.
 207          *
 208          * @param bool $yesno
 209          * @return $this
 210          */
 211         public function logStderr( $yesno = true ) {
 212                 $this->doLogStderr = $yesno;
 213
 214                 return $this;
 215         }
 216
 217         /**
 218          * Sets cgroup for this command
 219          *
 220          * @param string|false $cgroup Absolute file path to the cgroup, or false to not use a cgroup
 221          * @return $this
 222          */
 223         public function cgroup( $cgroup ) {
 224                 $this->cgroup = $cgroup;
 225
 226                 return $this;
 227         }
 228
 229         /**
 230          * Set additional restrictions for this request
 231          *
 232          * @since 1.31
 233          * @param int $restrictions
 234          * @return $this
 235          */
 236         public function restrict( $restrictions ) {
 237                 $this->restrictions |= $restrictions;
 238
 239                 return $this;
 240         }
 241
 242         /**
 243          * Bitfield helper on whether a specific restriction is enabled
 244          *
 245          * @param int $restriction
 246          *
 247          * @return bool
 248          */
 249         protected function hasRestriction( $restriction ) {
 250                 return ( $this->restrictions & $restriction ) === $restriction;
 251         }
 252
 253         /**
 254          * If called, only the files/directories that are
 255          * whitelisted will be available to the shell command.
 256          *
 257          * limit.sh will always be whitelisted
 258          *
 259          * @param string[] $paths
 260          *
 261          * @return $this
 262          */
 263         public function whitelistPaths( array $paths ) {
 264                 // Default implementation is a no-op
 265                 return $this;
 266         }
 267
 268         /**
 269          * String together all the options and build the final command
 270          * to execute
 271          *
 272          * @param string $command Already-escaped command to run
 273          * @return array [ command, whether to use log pipe ]
 274          */
 275         protected function buildFinalCommand( $command ) {
 276                 $envcmd = '';
 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.
 284                                  */
 285                                 $envcmd .= "set $k=" . preg_replace( '/([&|()<>^"])/', '^\\1', $v ) . '&& ';
 286                         } else {
 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
 289                                  */
 290                                 $envcmd .= "$k=" . escapeshellarg( $v ) . ' ';
 291                         }
 292                 }
 293
 294                 $useLogPipe = false;
 295                 $cmd = $envcmd . trim( $command );
 296
 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'] );
 302
 303                         if ( $time > 0 || $mem > 0 || $filesize > 0 || $wallTime > 0 ) {
 304                                 $cmd = '/bin/bash ' . escapeshellarg( __DIR__ . '/limit.sh' ) . ' ' .
 305                                         escapeshellarg( $cmd ) . ' ' .
 306                                         escapeshellarg(
 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"
 314                                         );
 315                                 $useLogPipe = true;
 316                         }
 317                 }
 318                 if ( !$useLogPipe && $this->doIncludeStderr ) {
 319                         $cmd .= ' 2>&1';
 320                 }
 321
 322                 return [ $cmd, $useLogPipe ];
 323         }
 324
 325         /**
 326          * Executes command. Afterwards, getExitCode() and getOutput() can be used to access execution
 327          * results.
 328          *
 329          * @return Result
 330          * @throws Exception
 331          * @throws ProcOpenError
 332          * @throws ShellDisabledError
 333          */
 334         public function execute() {
 335                 $this->everExecuted = true;
 336
 337                 $profileMethod = $this->method ?: wfGetCaller();
 338
 339                 list( $cmd, $useLogPipe ) = $this->buildFinalCommand( $this->command );
 340
 341                 $this->logger->debug( __METHOD__ . ": $cmd" );
 342
 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' );
 350                 }
 351
 352                 $desc = [
 353                         0 => [ 'file', 'php://stdin', 'r' ],
 354                         1 => [ 'pipe', 'w' ],
 355                         2 => [ 'pipe', 'w' ],
 356                 ];
 357                 if ( $useLogPipe ) {
 358                         $desc[3] = [ 'pipe', 'w' ];
 359                 }
 360                 $pipes = null;
 361                 $scoped = Profiler::instance()->scopedProfileIn( __FUNCTION__ . '-' . $profileMethod );
 362                 $proc = proc_open( $cmd, $desc, $pipes );
 363                 if ( !$proc ) {
 364                         $this->logger->error( "proc_open() failed: {command}", [ 'command' => $cmd ] );
 365                         throw new ProcOpenError();
 366                 }
 367                 $outBuffer = $logBuffer = '';
 368                 $errBuffer = null;
 369                 $emptyArray = [];
 370                 $status = false;
 371                 $logMsg = false;
 372
 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:
 377                  *
 378                  * stream_select(): unable to select [4]: Interrupted system call (max_fd=5)
 379                  *
 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.
 383                  */
 384                 $eintr = defined( 'SOCKET_EINTR' ) ? SOCKET_EINTR : 4;
 385                 $eintrMessage = "stream_select(): unable to select [$eintr]";
 386
 387                 $running = true;
 388                 $timeout = null;
 389                 $numReadyPipes = 0;
 390
 391                 while ( $running === true || $numReadyPipes !== 0 ) {
 392                         if ( $running ) {
 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'] ) {
 397                                         $running = false;
 398                                         $timeout = 0;
 399                                 }
 400                         }
 401
 402                         $readyPipes = $pipes;
 403
 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 () {
 408                         }, 0 );
 409                         // @codingStandardsIgnoreStart Generic.PHP.NoSilencedErrors.Discouraged
 410                         @trigger_error( '' );
 411                         // @codingStandardsIgnoreEnd
 412                         restore_error_handler();
 413
 414                         // @codingStandardsIgnoreStart Generic.PHP.NoSilencedErrors.Discouraged
 415                         $numReadyPipes = @stream_select( $readyPipes, $emptyArray, $emptyArray, $timeout );
 416                         // @codingStandardsIgnoreEnd
 417                         if ( $numReadyPipes === false ) {
 418                                 $error = error_get_last();
 419                                 if ( strncmp( $error['message'], $eintrMessage, strlen( $eintrMessage ) ) == 0 ) {
 420                                         continue;
 421                                 } else {
 422                                         trigger_error( $error['message'], E_USER_WARNING );
 423                                         $logMsg = $error['message'];
 424                                         break;
 425                                 }
 426                         }
 427                         foreach ( $readyPipes as $fd => $pipe ) {
 428                                 $block = fread( $pipe, 65536 );
 429                                 if ( $block === '' ) {
 430                                         // End of file
 431                                         fclose( $pipes[$fd] );
 432                                         unset( $pipes[$fd] );
 433                                         if ( !$pipes ) {
 434                                                 break 2;
 435                                         }
 436                                 } elseif ( $block === false ) {
 437                                         // Read error
 438                                         $logMsg = "Error reading from pipe";
 439                                         break 2;
 440                                 } elseif ( $fd == 1 ) {
 441                                         // From stdout
 442                                         $outBuffer .= $block;
 443                                 } elseif ( $fd == 2 ) {
 444                                         // From stderr
 445                                         $errBuffer .= $block;
 446                                 } elseif ( $fd == 3 ) {
 447                                         // From log FD
 448                                         $logBuffer .= $block;
 449                                         if ( strpos( $block, "\n" ) !== false ) {
 450                                                 $lines = explode( "\n", $logBuffer );
 451                                                 $logBuffer = array_pop( $lines );
 452                                                 foreach ( $lines as $line ) {
 453                                                         $this->logger->info( $line );
 454                                                 }
 455                                         }
 456                                 }
 457                         }
 458                 }
 459
 460                 foreach ( $pipes as $pipe ) {
 461                         fclose( $pipe );
 462                 }
 463
 464                 // Use the status previously collected if possible, since proc_get_status()
 465                 // just calls waitpid() which will not return anything useful the second time.
 466                 if ( $running ) {
 467                         $status = proc_get_status( $proc );
 468                 }
 469
 470                 if ( $logMsg !== false ) {
 471                         // Read/select error
 472                         $retval = -1;
 473                         proc_close( $proc );
 474                 } elseif ( $status['signaled'] ) {
 475                         $logMsg = "Exited with signal {$status['termsig']}";
 476                         $retval = 128 + $status['termsig'];
 477                         proc_close( $proc );
 478                 } else {
 479                         if ( $status['running'] ) {
 480                                 $retval = proc_close( $proc );
 481                         } else {
 482                                 $retval = $status['exitcode'];
 483                                 proc_close( $proc );
 484                         }
 485                         if ( $retval == 127 ) {
 486                                 $logMsg = "Possibly missing executable file";
 487                         } elseif ( $retval >= 129 && $retval <= 192 ) {
 488                                 $logMsg = "Probably exited with signal " . ( $retval - 128 );
 489                         }
 490                 }
 491
 492                 if ( $logMsg !== false ) {
 493                         $this->logger->warning( "$logMsg: {command}", [ 'command' => $cmd ] );
 494                 }
 495
 496                 if ( $errBuffer && $this->doLogStderr ) {
 497                         $this->logger->error( "Error running {command}: {error}", [
 498                                 'command' => $cmd,
 499                                 'error' => $errBuffer,
 500                                 'exitcode' => $retval,
 501                                 'exception' => new Exception( 'Shell error' ),
 502                         ] );
 503                 }
 504
 505                 return new Result( $retval, $outBuffer, $errBuffer );
 506         }
 507 }