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;
31 * Class used for executing shell commands
39 private $command = '';
60 private $useStderr = false;
63 private $everExecuted = false;
65 /** @var string|false */
66 private $cgroup = false;
69 * Constructor. Don't call directly, instead use Shell::command()
71 * @throws ShellDisabledError
73 public function __construct() {
74 if ( Shell::isDisabled() ) {
75 throw new ShellDisabledError();
78 $this->setLogger( new NullLogger() );
82 * Destructor. Makes sure programmer didn't forget to execute the command after all
84 public function __destruct() {
85 if ( !$this->everExecuted ) {
86 $context = [ 'command' => $this->command ];
87 $message = __CLASS__ . " was instantiated, but execute() was never called.";
88 if ( $this->method ) {
89 $message .= ' Calling method: {method}.';
90 $context['method'] = $this->method;
92 $message .= ' Command: {command}';
93 $this->logger->warning( $message, $context );
98 * Adds parameters to the command. All parameters are sanitized via Shell::escape().
99 * Null values are ignored.
101 * @param string|string[] $args,...
104 public function params( /* ... */ ) {
105 $args = func_get_args();
106 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
107 // If only one argument has been passed, and that argument is an array,
108 // treat it as a list of arguments
109 $args = reset( $args );
111 $this->command = trim( $this->command . ' ' . Shell::escape( $args ) );
117 * Adds unsafe parameters to the command. These parameters are NOT sanitized in any way.
118 * Null values are ignored.
120 * @param string|string[] $args,...
123 public function unsafeParams( /* ... */ ) {
124 $args = func_get_args();
125 if ( count( $args ) === 1 && is_array( reset( $args ) ) ) {
126 // If only one argument has been passed, and that argument is an array,
127 // treat it as a list of arguments
128 $args = reset( $args );
130 $args = array_filter( $args,
131 function ( $value ) {
132 return $value !== null;
135 $this->command = trim( $this->command . ' ' . implode( ' ', $args ) );
141 * Sets execution limits
143 * @param array $limits Associative array of limits. Keys (all optional):
144 * filesize (for ulimit -f), memory, time, walltime.
147 public function limits( array $limits ) {
148 if ( !isset( $limits['walltime'] ) && isset( $limits['time'] ) ) {
149 // Emulate the behavior of old wfShellExec() where walltime fell back on time
150 // if the latter was overridden and the former wasn't
151 $limits['walltime'] = $limits['time'];
153 $this->limits = $limits + $this->limits;
159 * Sets environment variables which should be added to the executed command environment
161 * @param string[] $env array of variable name => value
164 public function environment( array $env ) {
171 * Sets calling function for profiler. By default, the caller for execute() will be used.
173 * @param string $method
176 public function profileMethod( $method ) {
177 $this->method = $method;
183 * Controls whether stderr should be included in stdout, including errors from limit.sh.
184 * Default: don't include.
189 public function includeStderr( $yesno = true ) {
190 $this->useStderr = $yesno;
196 * Sets cgroup for this command
198 * @param string|false $cgroup Absolute file path to the cgroup, or false to not use a cgroup
201 public function cgroup( $cgroup ) {
202 $this->cgroup = $cgroup;
208 * Executes command. Afterwards, getExitCode() and getOutput() can be used to access execution
213 * @throws ProcOpenError
214 * @throws ShellDisabledError
216 public function execute() {
217 $this->everExecuted = true;
219 $profileMethod = $this->method ?: wfGetCaller();
222 foreach ( $this->env as $k => $v ) {
223 if ( wfIsWindows() ) {
224 /* Surrounding a set in quotes (method used by wfEscapeShellArg) makes the quotes themselves
225 * appear in the environment variable, so we must use carat escaping as documented in
226 * https://technet.microsoft.com/en-us/library/cc723564.aspx
227 * Note however that the quote isn't listed there, but is needed, and the parentheses
228 * are listed there but doesn't appear to need it.
230 $envcmd .= "set $k=" . preg_replace( '/([&|()<>^"])/', '^\\1', $v ) . '&& ';
232 /* Assume this is a POSIX shell, thus required to accept variable assignments before the command
233 * http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_09_01
235 $envcmd .= "$k=" . escapeshellarg( $v ) . ' ';
239 $cmd = $envcmd . trim( $this->command );
242 if ( is_executable( '/bin/bash' ) ) {
243 $time = intval( $this->limits['time'] );
244 $wallTime = intval( $this->limits['walltime'] );
245 $mem = intval( $this->limits['memory'] );
246 $filesize = intval( $this->limits['filesize'] );
248 if ( $time > 0 || $mem > 0 || $filesize > 0 || $wallTime > 0 ) {
249 $cmd = '/bin/bash ' . escapeshellarg( __DIR__ . '/limit.sh' ) . ' ' .
250 escapeshellarg( $cmd ) . ' ' .
252 "MW_INCLUDE_STDERR=" . ( $this->useStderr ? '1' : '' ) . ';' .
253 "MW_CPU_LIMIT=$time; " .
254 'MW_CGROUP=' . escapeshellarg( $this->cgroup ) . '; ' .
255 "MW_MEM_LIMIT=$mem; " .
256 "MW_FILE_SIZE_LIMIT=$filesize; " .
257 "MW_WALL_CLOCK_LIMIT=$wallTime; " .
258 "MW_USE_LOG_PIPE=yes"
261 } elseif ( $this->useStderr ) {
264 } elseif ( $this->useStderr ) {
267 wfDebug( __METHOD__ . ": $cmd\n" );
269 // Don't try to execute commands that exceed Linux's MAX_ARG_STRLEN.
270 // Other platforms may be more accomodating, but we don't want to be
271 // accomodating, because very long commands probably include user
272 // input. See T129506.
273 if ( strlen( $cmd ) > SHELL_MAX_ARG_STRLEN ) {
274 throw new Exception( __METHOD__ .
275 '(): total length of $cmd must not exceed SHELL_MAX_ARG_STRLEN' );
279 0 => [ 'file', 'php://stdin', 'r' ],
280 1 => [ 'pipe', 'w' ],
281 2 => [ 'file', 'php://stderr', 'w' ],
284 $desc[3] = [ 'pipe', 'w' ];
287 $scoped = Profiler::instance()->scopedProfileIn( __FUNCTION__ . '-' . $profileMethod );
288 $proc = proc_open( $cmd, $desc, $pipes );
290 $this->logger->error( "proc_open() failed: {command}", [ 'command' => $cmd ] );
291 throw new ProcOpenError();
293 $outBuffer = $logBuffer = '';
298 /* According to the documentation, it is possible for stream_select()
299 * to fail due to EINTR. I haven't managed to induce this in testing
300 * despite sending various signals. If it did happen, the error
301 * message would take the form:
303 * stream_select(): unable to select [4]: Interrupted system call (max_fd=5)
305 * where [4] is the value of the macro EINTR and "Interrupted system
306 * call" is string which according to the Linux manual is "possibly"
307 * localised according to LC_MESSAGES.
309 $eintr = defined( 'SOCKET_EINTR' ) ? SOCKET_EINTR : 4;
310 $eintrMessage = "stream_select(): unable to select [$eintr]";
316 while ( $running === true || $numReadyPipes !== 0 ) {
318 $status = proc_get_status( $proc );
319 // If the process has terminated, switch to nonblocking selects
320 // for getting any data still waiting to be read.
321 if ( !$status['running'] ) {
327 $readyPipes = $pipes;
329 \MediaWiki\suppressWarnings();
331 $numReadyPipes = stream_select( $readyPipes, $emptyArray, $emptyArray, $timeout );
332 \MediaWiki\restoreWarnings();
334 if ( $numReadyPipes === false ) {
335 // @codingStandardsIgnoreEnd
336 $error = error_get_last();
337 if ( strncmp( $error['message'], $eintrMessage, strlen( $eintrMessage ) ) == 0 ) {
340 trigger_error( $error['message'], E_USER_WARNING );
341 $logMsg = $error['message'];
345 foreach ( $readyPipes as $fd => $pipe ) {
346 $block = fread( $pipe, 65536 );
347 if ( $block === '' ) {
349 fclose( $pipes[$fd] );
350 unset( $pipes[$fd] );
354 } elseif ( $block === false ) {
356 $logMsg = "Error reading from pipe";
358 } elseif ( $fd == 1 ) {
360 $outBuffer .= $block;
361 } elseif ( $fd == 3 ) {
363 $logBuffer .= $block;
364 if ( strpos( $block, "\n" ) !== false ) {
365 $lines = explode( "\n", $logBuffer );
366 $logBuffer = array_pop( $lines );
367 foreach ( $lines as $line ) {
368 $this->logger->info( $line );
375 foreach ( $pipes as $pipe ) {
379 // Use the status previously collected if possible, since proc_get_status()
380 // just calls waitpid() which will not return anything useful the second time.
382 $status = proc_get_status( $proc );
385 if ( $logMsg !== false ) {
389 } elseif ( $status['signaled'] ) {
390 $logMsg = "Exited with signal {$status['termsig']}";
391 $retval = 128 + $status['termsig'];
394 if ( $status['running'] ) {
395 $retval = proc_close( $proc );
397 $retval = $status['exitcode'];
400 if ( $retval == 127 ) {
401 $logMsg = "Possibly missing executable file";
402 } elseif ( $retval >= 129 && $retval <= 192 ) {
403 $logMsg = "Probably exited with signal " . ( $retval - 128 );
407 if ( $logMsg !== false ) {
408 $this->logger->warning( "$logMsg: {command}", [ 'command' => $cmd ] );
411 return new Result( $retval, $outBuffer );