View source for Manual:Shell framework

__NOTOC__{{ptag|MediaWiki-Shell}}{{MW 1.30|and after|gerrit change=319505}}{{Notice|text=While not explicitly deprecated, it is recommended to use [[Manual:BoxedCommand|BoxedCommand (Shellbox)]] in new code for increased compatibility with running in containers and better security features.}}
MediaWiki provides a robust framework for shelling out to external commands for increased performance, security, and portability. See the documentation for {{class doclink|MediaWiki\Shell\Shell|Shell}} and {{class doclink|MediaWiki\Shell\Command|Command}}. A basic example:
<syntaxhighlight lang="php">
use MediaWiki\Shell\Shell;
use MediaWiki\Logger\LoggerFactory;

$result = Shell::command( '/usr/bin/command' )
    ->environment( [ 'VAR' => 'VALUE' ] )
    ->limits( [ 'time' => 300 ] )
    ->execute();

$exitCode = $result->getExitCode();
$output = $result->getStdout();
$error = $result->getStderr();
</syntaxhighlight>

This replaces the <code>wfShellExec()</code> global function, which is deprecated since MediaWiki 1.30, in favor of this new shell framework.

== Parameters ==
Most of the time you'll also want to provide some parameters to the command. MediaWiki will automatically escape all parameters to prevent shell injection attacks:
<syntaxhighlight lang="php">
$command = Shell::command( 'command', '--path' , $somePath );
</syntaxhighlight>

In the rare case you need to pass a parameter unscaped, you can use:
<syntaxhighlight lang="php">
$command = Shell::command( 'command' )->unsafeParams( '-x -y -z' );
</syntaxhighlight>

You can use <code>Shell::escape</code> to manually escape parts of an unescaped parameter.

== Limits ==
For both performance and security reasons, MediaWiki institutes limits on CPU time, wall clock time, file size and the memory usage a command can use. The defaults from {{wg|MaxShellTime}}, {{wg|MaxShellWallClockTime}}, {{wg|MaxShellMemory}}, and {{wg|MaxShellFileSize}} will be used unless overridden with a call to <code>->limits(...)</code>.

Further restrictions can be implemented using cgroups, see {{wg|ShellCgroup}} for more details.

== Restrictions ==
{{MW 1.31|and after|gerrit change=384930}}{{Deprecated|1.38|newvarname=BoxedCommand|newvarlink=Manual:BoxedCommand}}
Since 1.31, MediaWiki supports sandboxing commands with external restriction software - currently only [https://firejail.wordpress.com/ firejail] is supported, and must be enabled with {{wg|ShellRestrictionMethod}}. You can pass any of the following constants to <code>->restrict(...)</code>:
* {{phpi|Shell::RESTRICT_DEFAULT}} - a convenience constant equivalent to <code>NO_ROOT | SECCOMP | PRIVATE_DEV | NO_LOCALSETTINGS</code>
* {{phpi|Shell::NO_ROOT}} - Disallow any root access. Any [[:w:setuid|setuid]] binaries will be run without elevated access.
* {{phpi|Shell::SECCOMP}} - Use [[:w:seccomp|seccomp]] to block dangerous syscalls.
* {{phpi|Shell::PRIVATE_DEV}} - Create a private <code>/dev</code>
* {{phpi|Shell::NO_LOCALSETTINGS}} - Deny access to LocalSettings.php, which likely contains database passwords and other secrets.
* {{phpi|Shell::NO_NETWORK}} - Disallow any network access.
* {{phpi|Shell::NO_EXECVE}} - Deny the [[:w:exec_(system_call)|execve]] syscall with [[:w:seccomp|seccomp]] (basically preventing the program from calling other executables). {{phpi|Shell::SECCOMP}} must also be set.

You can look at [[gerrit:393830|the restriction of binaries in the Score extension]] as an example.

=== firejail profile ===
MediaWiki uses a firejail profile that allows for extra customization and restrictions depending upon your platform. Create <code>/etc/firejail/mediawiki.local</code> ([https://firejail.wordpress.com/features-3/man-firejail-profile syntax]) to restrict other paths that might have secret information, e.g.:
<pre>
# MediaWiki local firejail additions
blacklist /srv/private
</pre>

See [[gerrit:609840|Wikimedia's mediawiki.local]] as an example.

== Logging ==
By default, errors and standard error output are logged to the <code>exec</code> channel in a [[Manual:Structured logging|structured form]]. A different logger can be set via the standard PSR-3 <code>LoggerAwareInterface</code>.