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         private $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 $useStderr = false;
  61
  62         /** @var bool */
  63         private $everExecuted = false;
  64
  65         /** @var string|false */
  66         private $cGroup = false;
  67
  68         /**
  69          * Constructor. Don't call directly, instead use Shell::command()
  70          *
  71          * @throws ShellDisabledError
  72          */
  73         public function __construct() {
  74                 if ( Shell::isDisabled() ) {
  75                         throw new ShellDisabledError();
  76                 }
  77
  78                 $this->setLogger( new NullLogger() );
  79         }
  80
  81         /**
  82          * Destructor. Makes sure programmer didn't forget to execute the command after all
  83          */
  84         public function __destruct() {
  85                 if ( !$this->everExecuted ) {
  86                         $message = __CLASS__ . " was instantiated, but execute() was never called.";
  87                         if ( $this->method ) {
  88                                 $message .= " Calling method: {$this->method}.";
  89                         }
  90                         $message .= " Command: {$this->command}";
  91                         trigger_error( $message, E_USER_NOTICE );
  92                 }
  93         }
  94
  95         /**
  96          * Adds parameters to the command. All parameters are sanitized via Shell::escape().
  97          *
  98          * @param string|string[] $args,...
  99          * @return $this
 100          */
 101         public function params( /* ... */ ) {
 102                 $args = func_get_args();
 103                 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
 104                         // If only one argument has been passed, and that argument is an array,
 105                         // treat it as a list of arguments
 106                         $args = reset( $args );
 107                 }
 108                 $this->command .= ' ' . Shell::escape( $args );
 109
 110                 return $this;
 111         }
 112
 113         /**
 114          * Adds unsafe parameters to the command. These parameters are NOT sanitized in any way.
 115          *
 116          * @param string|string[] $args,...
 117          * @return $this
 118          */
 119         public function unsafeParams( /* ... */ ) {
 120                 $args = func_get_args();
 121                 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
 122                         // If only one argument has been passed, and that argument is an array,
 123                         // treat it as a list of arguments
 124                         $args = reset( $args );
 125                 }
 126                 $this->command .= implode( ' ', $args );
 127
 128                 return $this;
 129         }
 130
 131         /**
 132          * Sets execution limits
 133          *
 134          * @param array $limits Optional array with limits(filesize, memory, time, walltime).
 135          * @return $this
 136          */
 137         public function limits( array $limits ) {
 138                 $this->limits = $limits + $this->limits;
 139
 140                 return $this;
 141         }
 142
 143         /**
 144          * Sets environment variables which should be added to the executed command environment
 145          *
 146          * @param string[] $env array of variable name => value
 147          * @return $this
 148          */
 149         public function environment( array $env ) {
 150                 $this->env = $env;
 151
 152                 return $this;
 153         }
 154
 155         /**
 156          * Sets calling function for profiler. By default, the caller for execute() will be used.
 157          *
 158          * @param string $method
 159          * @return $this
 160          */
 161         public function profileMethod( $method ) {
 162                 $this->method = $method;
 163
 164                 return $this;
 165         }
 166
 167         /**
 168          * Controls whether stderr should be included in stdout, including errors from limit.sh.
 169          * Default: don't include.
 170          *
 171          * @param bool $yesno
 172          * @return $this
 173          */
 174         public function includeStderr( $yesno = true ) {
 175                 $this->useStderr = $yesno;
 176
 177                 return $this;
 178         }
 179
 180         /**
 181          * Sets cgroup for this command
 182          *
 183          * @param string|false $cgroup
 184          * @return $this
 185          */
 186         public function cgroup( $cgroup ) {
 187                 $this->cGroup = $cgroup;
 188
 189                 return $this;
 190         }
 191
 192         /**
 193          * Executes command. Afterwards, getExitCode() and getOutput() can be used to access execution
 194          * results.
 195          *
 196          * @return Result
 197          * @throws Exception
 198          * @throws ProcOpenError
 199          * @throws ShellDisabledError
 200          */
 201         public function execute() {
 202                 global $IP;
 203
 204                 $this->everExecuted = true;
 205
 206                 $profileMethod = $this->method ?: wfGetCaller();
 207
 208                 $envcmd = '';
 209                 foreach ( $this->env as $k => $v ) {
 210                         if ( wfIsWindows() ) {
 211                                 /* Surrounding a set in quotes (method used by wfEscapeShellArg) makes the quotes themselves
 212                                  * appear in the environment variable, so we must use carat escaping as documented in
 213                                  * https://technet.microsoft.com/en-us/library/cc723564.aspx
 214                                  * Note however that the quote isn't listed there, but is needed, and the parentheses
 215                                  * are listed there but doesn't appear to need it.
 216                                  */
 217                                 $envcmd .= "set $k=" . preg_replace( '/([&|()<>^"])/', '^\\1', $v ) . '&& ';
 218                         } else {
 219                                 /* Assume this is a POSIX shell, thus required to accept variable assignments before the command
 220                                  * http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_01
 221                                  */
 222                                 $envcmd .= "$k=" . escapeshellarg( $v ) . ' ';
 223                         }
 224                 }
 225
 226                 $cmd = $envcmd . trim( $this->command );
 227
 228                 $useLogPipe = false;
 229                 if ( is_executable( '/bin/bash' ) ) {
 230                         $time = intval( $this->limits['time'] );
 231                         $wallTime = intval( $this->limits['walltime'] );
 232                         // for b/c, wall time falls back to time
 233                         $wallTime = min( $time, $wallTime );
 234                         $mem = intval( $this->limits['memory'] );
 235                         $filesize = intval( $this->limits['filesize'] );
 236
 237                         if ( $time > 0 || $mem > 0 || $filesize > 0 || $wallTime > 0 ) {
 238                                 $cmd = '/bin/bash ' . escapeshellarg( "$IP/includes/limit.sh" ) . ' ' .
 239                                            escapeshellarg( $cmd ) . ' ' .
 240                                            escapeshellarg(
 241                                                    "MW_INCLUDE_STDERR=" . ( $this->useStderr ? '1' : '' ) . ';' .
 242                                                    "MW_CPU_LIMIT=$time; " .
 243                                                    'MW_CGROUP=' . escapeshellarg( $this->cGroup ) . '; ' .
 244                                                    "MW_MEM_LIMIT=$mem; " .
 245                                                    "MW_FILE_SIZE_LIMIT=$filesize; " .
 246                                                    "MW_WALL_CLOCK_LIMIT=$wallTime; " .
 247                                                    "MW_USE_LOG_PIPE=yes"
 248                                            );
 249                                 $useLogPipe = true;
 250                         } elseif ( $this->useStderr ) {
 251                                 $cmd .= ' 2>&1';
 252                         }
 253                 } elseif ( $this->useStderr ) {
 254                         $cmd .= ' 2>&1';
 255                 }
 256                 wfDebug( __METHOD__ . ": $cmd\n" );
 257
 258                 // Don't try to execute commands that exceed Linux's MAX_ARG_STRLEN.
 259                 // Other platforms may be more accomodating, but we don't want to be
 260                 // accomodating, because very long commands probably include user
 261                 // input. See T129506.
 262                 if ( strlen( $cmd ) > SHELL_MAX_ARG_STRLEN ) {
 263                         throw new Exception( __METHOD__ .
 264                                                                  '(): total length of $cmd must not exceed SHELL_MAX_ARG_STRLEN' );
 265                 }
 266
 267                 $desc = [
 268                         0 => [ 'file', 'php://stdin', 'r' ],
 269                         1 => [ 'pipe', 'w' ],
 270                         2 => [ 'file', 'php://stderr', 'w' ],
 271                 ];
 272                 if ( $useLogPipe ) {
 273                         $desc[3] = [ 'pipe', 'w' ];
 274                 }
 275                 $pipes = null;
 276                 $scoped = Profiler::instance()->scopedProfileIn( __FUNCTION__ . '-' . $profileMethod );
 277                 $proc = proc_open( $cmd, $desc, $pipes );
 278                 if ( !$proc ) {
 279                         $this->logger->error( "proc_open() failed: {command}", [ 'command' => $cmd ] );
 280                         throw new ProcOpenError();
 281                 }
 282                 $outBuffer = $logBuffer = '';
 283                 $emptyArray = [];
 284                 $status = false;
 285                 $logMsg = false;
 286
 287                 /* According to the documentation, it is possible for stream_select()
 288                  * to fail due to EINTR. I haven't managed to induce this in testing
 289                  * despite sending various signals. If it did happen, the error
 290                  * message would take the form:
 291                  *
 292                  * stream_select(): unable to select [4]: Interrupted system call (max_fd=5)
 293                  *
 294                  * where [4] is the value of the macro EINTR and "Interrupted system
 295                  * call" is string which according to the Linux manual is "possibly"
 296                  * localised according to LC_MESSAGES.
 297                  */
 298                 $eintr = defined( 'SOCKET_EINTR' ) ? SOCKET_EINTR : 4;
 299                 $eintrMessage = "stream_select(): unable to select [$eintr]";
 300
 301                 $running = true;
 302                 $timeout = null;
 303                 $numReadyPipes = 0;
 304
 305                 while ( $running === true || $numReadyPipes !== 0 ) {
 306                         if ( $running ) {
 307                                 $status = proc_get_status( $proc );
 308                                 // If the process has terminated, switch to nonblocking selects
 309                                 // for getting any data still waiting to be read.
 310                                 if ( !$status['running'] ) {
 311                                         $running = false;
 312                                         $timeout = 0;
 313                                 }
 314                         }
 315
 316                         $readyPipes = $pipes;
 317
 318                         // Clear last error
 319                         // @codingStandardsIgnoreStart Generic.PHP.NoSilencedErrors.Discouraged
 320                         @trigger_error( '' );
 321                         $numReadyPipes = @stream_select( $readyPipes, $emptyArray, $emptyArray, $timeout );
 322                         if ( $numReadyPipes === false ) {
 323                                 // @codingStandardsIgnoreEnd
 324                                 $error = error_get_last();
 325                                 if ( strncmp( $error['message'], $eintrMessage, strlen( $eintrMessage ) ) == 0 ) {
 326                                         continue;
 327                                 } else {
 328                                         trigger_error( $error['message'], E_USER_WARNING );
 329                                         $logMsg = $error['message'];
 330                                         break;
 331                                 }
 332                         }
 333                         foreach ( $readyPipes as $fd => $pipe ) {
 334                                 $block = fread( $pipe, 65536 );
 335                                 if ( $block === '' ) {
 336                                         // End of file
 337                                         fclose( $pipes[$fd] );
 338                                         unset( $pipes[$fd] );
 339                                         if ( !$pipes ) {
 340                                                 break 2;
 341                                         }
 342                                 } elseif ( $block === false ) {
 343                                         // Read error
 344                                         $logMsg = "Error reading from pipe";
 345                                         break 2;
 346                                 } elseif ( $fd == 1 ) {
 347                                         // From stdout
 348                                         $outBuffer .= $block;
 349                                 } elseif ( $fd == 3 ) {
 350                                         // From log FD
 351                                         $logBuffer .= $block;
 352                                         if ( strpos( $block, "\n" ) !== false ) {
 353                                                 $lines = explode( "\n", $logBuffer );
 354                                                 $logBuffer = array_pop( $lines );
 355                                                 foreach ( $lines as $line ) {
 356                                                         $this->logger->info( $line );
 357                                                 }
 358                                         }
 359                                 }
 360                         }
 361                 }
 362
 363                 foreach ( $pipes as $pipe ) {
 364                         fclose( $pipe );
 365                 }
 366
 367                 // Use the status previously collected if possible, since proc_get_status()
 368                 // just calls waitpid() which will not return anything useful the second time.
 369                 if ( $running ) {
 370                         $status = proc_get_status( $proc );
 371                 }
 372
 373                 if ( $logMsg !== false ) {
 374                         // Read/select error
 375                         $retval = -1;
 376                         proc_close( $proc );
 377                 } elseif ( $status['signaled'] ) {
 378                         $logMsg = "Exited with signal {$status['termsig']}";
 379                         $retval = 128 + $status['termsig'];
 380                         proc_close( $proc );
 381                 } else {
 382                         if ( $status['running'] ) {
 383                                 $retval = proc_close( $proc );
 384                         } else {
 385                                 $retval = $status['exitcode'];
 386                                 proc_close( $proc );
 387                         }
 388                         if ( $retval == 127 ) {
 389                                 $logMsg = "Possibly missing executable file";
 390                         } elseif ( $retval >= 129 && $retval <= 192 ) {
 391                                 $logMsg = "Probably exited with signal " . ( $retval - 128 );
 392                         }
 393                 }
 394
 395                 if ( $logMsg !== false ) {
 396                         $this->logger->warning( "$logMsg: {command}", [ 'command' => $cmd ] );
 397                 }
 398
 399                 return new Result( $retval, $outBuffer );
 400         }
 401 }