Source of: /manual/en/ini.sect.safe-mode.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/features.safe-mode.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'ini.sect.safe-mode.php',
1 => 'Security and Safe Mode',
),
'up' =>
array (
0 => 'features.safe-mode.php',
1 => 'Safe Mode',
),
'prev' =>
array (
0 => 'features.safe-mode.php',
1 => 'Safe Mode',
),
'next' =>
array (
0 => 'features.safe-mode.functions.php',
1 => 'Functions restricted/disabled by safe mode',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="ini.sect.safe-mode" class="sect1">
<h2 class="title">Security and Safe Mode</h2>
<p class="para">
</p><table class="doctable table">
<caption><b>Security and Safe Mode Configuration Directives</b></caption>
<thead valign="middle">
<tr valign="middle">
<th>Name</th>
<th>Default</th>
<th>Changeable</th>
<th>Changelog</th>
</tr>
</thead>
<tbody valign="middle" class="tbody">
<tr valign="middle">
<td align="left">safe_mode</td>
<td align="left">"0"</td>
<td align="left">PHP_INI_SYSTEM</td>
<td align="left">Removed in PHP 6.0.0.</td>
</tr>
<tr valign="middle">
<td align="left">safe_mode_gid</td>
<td align="left">"0"</td>
<td align="left">PHP_INI_SYSTEM</td>
<td align="left">Available since PHP 4.1.0. Removed in PHP 6.0.0.</td>
</tr>
<tr valign="middle">
<td align="left">safe_mode_include_dir</td>
<td align="left">NULL</td>
<td align="left">PHP_INI_SYSTEM</td>
<td align="left">Available since PHP 4.1.0. Removed in PHP 6.0.0.</td>
</tr>
<tr valign="middle">
<td align="left">safe_mode_exec_dir</td>
<td align="left">""</td>
<td align="left">PHP_INI_SYSTEM</td>
<td align="left">Removed in PHP 6.0.0.</td>
</tr>
<tr valign="middle">
<td align="left">safe_mode_allowed_env_vars</td>
<td align="left">"PHP_"</td>
<td align="left">PHP_INI_SYSTEM</td>
<td align="left">Removed in PHP 6.0.0.</td>
</tr>
<tr valign="middle">
<td align="left">safe_mode_protected_env_vars</td>
<td align="left">"LD_LIBRARY_PATH"</td>
<td align="left">PHP_INI_SYSTEM</td>
<td align="left">Removed in PHP 6.0.0.</td>
</tr>
<tr valign="middle">
<td align="left">open_basedir</td>
<td align="left">NULL</td>
<td align="left">PHP_INI_ALL</td>
<td align="left">PHP_INI_SYSTEM in PHP < 5.3.0</td>
</tr>
<tr valign="middle">
<td align="left">disable_functions</td>
<td align="left">""</td>
<td align="left"><var class="filename">php.ini</var> only</td>
<td align="left">Available since PHP 4.0.1.</td>
</tr>
<tr valign="middle">
<td align="left">disable_classes</td>
<td align="left">""</td>
<td align="left"><var class="filename">php.ini</var> only</td>
<td align="left">Available since PHP 4.3.2.</td>
</tr>
</tbody>
</table>
<p>
For further details and definitions of the
PHP_INI_* modes, see the <a href="configuration.changes.modes.php" class="xref">Where a configuration setting may be set</a>.
</p>
<p class="para">Here's a short explanation of
the configuration directives.</p>
<p class="para">
</p><dl>
<dt id="ini.safe-mode" class="varlistentry">
<span class="term">
<i><tt class="parameter">safe_mode</tt></i>
<a href="language.types.boolean.php" class="type boolean">boolean</a>
</span>
</dt><dd class="listitem">
<p class="para">
Whether to enable PHP's safe mode.
If PHP is compiled with <i>--enable-safe-mode</i> then
defaults to On, otherwise Off.
</p>
<div class="warning"><b class="warning">Warning</b><p class="simpara">This feature has been
<em class="emphasis">DEPRECATED</em> as of PHP 5.3.0 and <em class="emphasis">REMOVED</em> as of PHP 6.0.0.
Relying on this feature is highly discouraged.</p></div>
</dd>
<dt id="ini.safe-mode-gid" class="varlistentry">
<span class="term">
<i><tt class="parameter">safe_mode_gid</tt></i>
<a href="language.types.boolean.php" class="type boolean">boolean</a>
</span>
</dt><dd class="listitem">
<p class="para">
By default, Safe Mode does a UID compare check when
opening files. If you want to relax this to a GID compare,
then turn on safe_mode_gid.
Whether to use <i>UID</i> (<b><tt class="constant">FALSE</tt></b>) or
<i>GID</i> (<b><tt class="constant">TRUE</tt></b>) checking upon file
access.
</p>
</dd>
<dt id="ini.safe-mode-include-dir" class="varlistentry">
<span class="term">
<i><tt class="parameter">safe_mode_include_dir</tt></i>
<a href="language.types.string.php" class="type string">string</a>
</span>
</dt><dd class="listitem">
<p class="para">
<i>UID</i>/<i>GID</i> checks are bypassed when
including files from this directory and its subdirectories (directory
must also be in <a href="ini.core.php#ini.include-path" class="link">include_path</a>
or full path must including).
</p>
<span class="simpara">
As of PHP 4.2.0, this directive can take a colon (semi-colon on
Windows) separated path in a fashion similar to the
<a href="ini.core.php#ini.include-path" class="link">include_path</a> directive,
rather than just a single directory.
</span>
<span class="simpara">
The restriction specified is actually a prefix, not a directory name.
This means that "<i>safe_mode_include_dir = /dir/incl</i>" also allows
access to "<i>/dir/include</i>" and
"<i>/dir/incls</i>" if they exist. When you
want to restrict access to only the specified directory, end with a
slash. For example: "<i>safe_mode_include_dir = /dir/incl/</i>"
</span>
<span class="simpara">
If the value of this directive is empty, no files with different
<i>UID</i>/<i>GID</i> can be included in
PHP 4.2.3 and as of PHP 4.3.3. In earlier versions, all files could be
included.
</span>
</dd>
<dt id="ini.safe-mode-exec-dir" class="varlistentry">
<span class="term">
<i><tt class="parameter">safe_mode_exec_dir</tt></i>
<a href="language.types.string.php" class="type string">string</a>
</span>
</dt><dd class="listitem">
<p class="para">
If PHP is used in safe mode, <a href="function.system.php" class="function">system()</a> and the other
<a href="ref.exec.php" class="link">functions executing system programs</a>
refuse to start programs that are not in this directory.
You have to use <i>/</i> as directory separator on all
environments including Windows.
</p>
</dd>
<dt id="ini.safe-mode-allowed-env-vars" class="varlistentry">
<span class="term">
<i><tt class="parameter">safe_mode_allowed_env_vars</tt></i>
<a href="language.types.string.php" class="type string">string</a>
</span>
</dt><dd class="listitem">
<p class="para">
Setting certain environment variables may be a potential security breach.
This directive contains a comma-delimited list of prefixes. In Safe Mode,
the user may only alter environment variables whose names begin with the
prefixes supplied here. By default, users will only be able to set
environment variables that begin with <i>PHP_</i>
(e.g. <i>PHP_FOO=BAR</i>).
</p>
<blockquote><p><b class="note">Note</b>:
If this directive is empty, PHP will let the user modify ANY
environment variable!
<br />
</p></blockquote>
</dd>
<dt id="ini.safe-mode-protected-env-vars" class="varlistentry">
<span class="term">
<i><tt class="parameter">safe_mode_protected_env_vars</tt></i>
<a href="language.types.string.php" class="type string">string</a>
</span>
</dt><dd class="listitem">
<p class="para">
This directive contains a comma-delimited list of environment
variables that the end user won't be able to change using
<a href="function.putenv.php" class="function">putenv()</a>. These variables will be protected
even if safe_mode_allowed_env_vars is set to allow to change them.
</p>
</dd>
<dt id="ini.open-basedir" class="varlistentry">
<span class="term">
<i><tt class="parameter">open_basedir</tt></i>
<a href="language.types.string.php" class="type string">string</a>
</span>
</dt><dd class="listitem">
<p class="para">
Limit the files that can be opened by PHP to the specified
directory-tree, including the file itself. This directive
is <em class="emphasis">NOT</em> affected by whether Safe Mode is
turned On or Off.
</p>
<p class="para">
When a script tries to open a file with, for example,
<a href="function.fopen.php" class="function">fopen()</a> or <a href="function.gzopen.php" class="function">gzopen()</a>,
the location of the file is checked. When the file is outside the
specified directory-tree, PHP will refuse to open it. All symbolic
links are resolved, so it's not possible to avoid this restriction
with a symlink. If the file doesn't exist then the symlink couldn't be
resolved and the filename is compared to (a resolved)
<span class="option">open_basedir</span>.
</p>
<p class="para">
The special value <code class="systemitem systemitem">.</code>
indicates that the working directory of the script will be used as the
base-directory. This is, however, a little dangerous as the working directory
of the script can easily be changed with <a href="function.chdir.php" class="function">chdir()</a>.
</p>
<p class="para">
In <var class="filename">httpd.conf</var>, <span class="option">open_basedir</span> can be turned off
(e.g. for some virtual hosts)
<a href="configuration.changes.php#configuration.changes.apache" class="link">the same way</a> as
any other configuration directive with "<i>php_admin_value open_basedir
none</i>".
</p>
<p class="para">
Under Windows, separate the directories with a semicolon. On all
other systems, separate the directories with a colon. As an Apache
module, <span class="option">open_basedir</span> paths from parent directories are now
automatically inherited.
</p>
<p class="para">
The restriction specified with <span class="option">open_basedir</span> is actually a
prefix, not a directory name. This means that "<i>open_basedir
= /dir/incl</i>" also allows access to "<i>/dir/include</i>" and
"<i>/dir/incls</i>" if they exist. When you want to restrict access
to only the specified directory, end with a slash. For example:
<i>open_basedir = /dir/incl/</i>
</p>
<p class="para">
The default is to allow all files to be opened.
</p>
<blockquote><p><b class="note">Note</b>:
As of PHP 5.3.0 open_basedir can be tightened at run-time. This means
that if open_basedir is set to <i>/www/</i> in <var class="filename">php.ini</var>
a script can tighten the configuration to
<i>/www/tmp/</i> at run-time with
<a href="function.ini-set.php" class="function">ini_set()</a>
<br />
</p></blockquote>
</dd>
<dt id="ini.disable-functions" class="varlistentry">
<span class="term">
<i><tt class="parameter">disable_functions</tt></i>
<a href="language.types.string.php" class="type string">string</a>
</span>
</dt><dd class="listitem">
<span class="simpara">
This directive allows you to disable certain functions for
<a href="security.php" class="link">security</a> reasons. It takes
on a comma-delimited list of function names. disable_functions
is not affected by <a href="ini.sect.safe-mode.php#ini.safe-mode" class="link">Safe Mode</a>.
</span>
<span class="simpara">
This directive must be set in <var class="filename">php.ini</var> For example, you
cannot set this in <var class="filename">httpd.conf</var>.
</span>
</dd>
<dt id="ini.disable-classes" class="varlistentry">
<span class="term">
<i><tt class="parameter">disable_classes</tt></i>
<a href="language.types.string.php" class="type string">string</a>
</span>
</dt><dd class="listitem">
<span class="simpara">
This directive allows you to disable certain classes for
<a href="security.php" class="link">security</a> reasons. It takes
on a comma-delimited list of class names. disable_classes
is not affected by <a href="ini.sect.safe-mode.php#ini.safe-mode" class="link">Safe Mode</a>.
</span>
<span class="simpara">
This directive must be set in <var class="filename">php.ini</var> For example, you
cannot set this in <var class="filename">httpd.conf</var>.
</span>
<blockquote><p><b class="note">Note</b>:
<b>Availability note</b><br />
<span class="simpara">
This directive became available in PHP 4.3.2
</span>
</p></blockquote>
</dd>
</dl>
<p>
</p>
<p class="para">
See also: <a href="ini.core.php#ini.register-globals" class="link">register_globals</a>,
<a href="errorfunc.configuration.php#ini.display-errors" class="link">display_errors</a>, and
<a href="errorfunc.configuration.php#ini.log-errors" class="link">log_errors</a>.
</p>
<p class="para">
When <a href="ini.sect.safe-mode.php#ini.safe-mode" class="link">safe_mode</a> is on, PHP checks to see
if the owner of the current script matches the owner of the file to be
operated on by a file function or its directory. For example:
</p><div class="example-contents programlisting">
<div class="lscode"><pre class="lscode">-rw-rw-r-- 1 rasmus rasmus 33 Jul 1 19:20 script.php
-rw-r--r-- 1 root root 1116 May 26 18:01 /etc/passwd</pre>
</div>
</div>
<p>
Running <var class="filename">script.php</var>:
</p><div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /> readfile</span><span style="color: #007700">(</span><span style="color: #DD0000">'/etc/passwd'</span><span style="color: #007700">); <br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<p>
results in this error when safe mode is enabled:
<div class="example-contents screen">
<div class="cdata"><pre>
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not
allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2
</pre></div>
</div>
</p>
<p class="para">
However, there may be environments where a strict <i>UID</i>
check is not appropriate and a relaxed <i>GID</i> check is
sufficient. This is supported by means of the <a href="ini.sect.safe-mode.php#ini.safe-mode-gid" class="link">safe_mode_gid</a> switch. Setting it to
<i>On</i> performs the relaxed <i>GID</i> checking,
setting it to <i>Off</i> (the default) performs
<i>UID</i> checking.
</p>
<p class="para">
If instead of <a href="ini.sect.safe-mode.php#ini.safe-mode" class="link">safe_mode</a>, you set an
<a href="ini.sect.safe-mode.php#ini.open-basedir" class="link">open_basedir</a> directory then all
file operations will be limited to files under the specified directory.
For example (Apache <var class="filename">httpd.conf</var> example):
</p><div class="example-contents programlisting">
<div class="inicode"><pre class="inicode"><Directory /docroot>
php_admin_value open_basedir /docroot
</Directory></pre>
</div>
</div>
<p>
If you run the same <var class="filename">script.php</var> with this
<a href="ini.sect.safe-mode.php#ini.open-basedir" class="link">open_basedir</a> setting
then this is the result:
<div class="example-contents screen">
<div class="cdata"><pre>
Warning: open_basedir restriction in effect. File is in wrong directory in
/docroot/script.php on line 2
</pre></div>
</div>
</p>
<p class="para">
You can also disable individual functions. Note that the
<a href="ini.sect.safe-mode.php#ini.disable-functions" class="link">disable_functions</a>
directive can not be used outside of the <var class="filename">php.ini</var> file which means that
you cannot disable functions on a per-virtualhost or per-directory basis
in your <var class="filename">httpd.conf</var> file.
If we add this to our <var class="filename">php.ini</var> file:
</p><div class="example-contents programlisting">
<div class="inicode"><pre class="inicode">disable_functions = readfile,system</pre>
</div>
</div>
<p>
Then we get this output:
<div class="example-contents screen">
<div class="cdata"><pre>
Warning: readfile() has been disabled for security reasons in
/docroot/script.php on line 2
</pre></div>
</div>
</p>
<div class="warning"><b class="warning">Warning</b>
<p class="para">
These PHP restrictions are not valid in executed binaries, of course.
</p>
</div>
</div><?php manual_footer(); ?>
