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