<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.65 $ -->
 <chapter id="features.safe-mode">
  <title>Safe Mode</title>

  <para>
   The PHP safe mode is an attempt to solve the shared-server security
   problem. It is architecturally incorrect to try to solve this
   problem at the PHP level, but since the alternatives at the web
   server and OS levels aren't very realistic, many people,
   especially ISP's, use safe mode for now. 
  </para>
  <warning>
   <para>
    Safe Mode was removed in PHP 6.0.0.
   </para>
  </warning>

  <sect1 id="ini.sect.safe-mode">
   <title>Security and Safe Mode</title>
   <para>
    <table>
     <title>Security and Safe Mode Configuration Directives</title>
     <tgroup cols="4">
      <thead>
       <row>
        <entry>Name</entry>
        <entry>Default</entry>
        <entry>Changeable</entry>
        <entry>Changelog</entry>
       </row>
      </thead>
      <tbody>
      <row>
       <entry>safe_mode</entry>
       <entry>"0"</entry>
       <entry>PHP_INI_SYSTEM</entry>
       <entry></entry>
      </row>
      <row>
       <entry>safe_mode_gid</entry>
       <entry>"0"</entry>
       <entry>PHP_INI_SYSTEM</entry>
       <entry>Available since PHP 4.1.0.</entry>
      </row>
      <row>
       <entry>safe_mode_include_dir</entry>
       <entry>NULL</entry>
       <entry>PHP_INI_SYSTEM</entry>
       <entry>Available since PHP 4.1.0.</entry>
      </row>
      <row>
       <entry>safe_mode_exec_dir</entry>
       <entry>""</entry>
       <entry>PHP_INI_SYSTEM</entry>
       <entry></entry>
      </row>
      <row>
       <entry>safe_mode_allowed_env_vars</entry>
       <entry>"PHP_"</entry>
       <entry>PHP_INI_SYSTEM</entry>
       <entry></entry>
      </row>
      <row>
       <entry>safe_mode_protected_env_vars</entry>
       <entry>"LD_LIBRARY_PATH"</entry>
       <entry>PHP_INI_SYSTEM</entry>
       <entry></entry>
      </row>
      <row>
       <entry>open_basedir</entry>
       <entry>NULL</entry>
       <entry>PHP_INI_SYSTEM</entry>
       <entry></entry>
      </row>
      <row>
       <entry>disable_functions</entry>
       <entry>""</entry>
       <entry>&php.ini; only</entry>
       <entry>Available since PHP 4.0.1.</entry>
      </row>
      <row>
       <entry>disable_classes</entry>
       <entry>""</entry>
       <entry>&php.ini; only</entry>
       <entry>Available since PHP 4.3.2.</entry>
      </row>
      </tbody>
     </tgroup>
    </table>
    For further details and definition of the PHP_INI_* constants see
    <function>ini_set</function>.
   </para>
   
   &ini.descriptions.title;
   
   <para>
    <variablelist>
     <varlistentry id="ini.safe-mode">
      <term>
       <parameter>safe_mode</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
        Whether to enable PHP's safe mode.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.safe-mode-gid">
      <term>
       <parameter>safe_mode_gid</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <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 <literal>UID</literal> (&false;) or
        <literal>GID</literal> (&true;) checking upon file
        access.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.safe-mode-include-dir">
      <term>
       <parameter>safe_mode_include_dir</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        <literal>UID</literal>/<literal>GID</literal> checks are bypassed when
        including files from this directory and its subdirectories (directory
        must also be in <link linkend="ini.include-path">include_path</link>
        or full path must including).
       </para>
       <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
        <link linkend="ini.include-path">include_path</link> directive,
        rather than just a single directory.
       </simpara>
       <simpara>
        The restriction specified is actually a prefix, not a directory name. 
        This means that "safe_mode_include_dir = /dir/incl" also allows
        access to "/dir/include" and "/dir/incls" if they exist.  When you 
        want to restrict access to only the specified directory, end with a 
        slash. For example: "safe_mode_include_dir = /dir/incl/"
       </simpara>
       <simpara>
        If the value of this directive is empty, no files with different
        <literal>UID</literal>/<literal>GID</literal> can be included in
        PHP 4.2.3 and as of PHP 4.3.3. In earlier versions, all files could be
        included.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.safe-mode-exec-dir">
      <term>
       <parameter>safe_mode_exec_dir</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        If PHP is used in safe mode, <function>system</function> and the other
        <link linkend="ref.exec">functions executing system programs</link>
        refuse to start programs that are not in this directory.
        You have to use <literal>/</literal> as directory separator on all
        environments including Windows.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.safe-mode-allowed-env-vars">
      <term>
       <parameter>safe_mode_allowed_env_vars</parameter>
       <type>string</type>
      </term>
      <listitem>
       <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 PHP_ (e.g. PHP_FOO=BAR).
       </para>
       <note>
        <para>
         If this directive is empty, PHP will let the user modify ANY
         environment variable!
        </para>
       </note>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.safe-mode-protected-env-vars">
      <term>
       <parameter>safe_mode_protected_env_vars</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        This directive contains a comma-delimited list of environment
        variables that the end user won't be able to change using
        <function>putenv</function>. These variables will be protected
        even if safe_mode_allowed_env_vars is set to allow to change them.
       </para>
      </listitem>
     </varlistentry>
      <varlistentry id="ini.open-basedir">
      <term>
       <parameter>open_basedir</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        Limit the files that can be opened by PHP to the specified
        directory-tree, including the file itself.  This directive 
        is <emphasis>NOT</emphasis> affected by whether Safe Mode is 
        turned On or Off.
       </para>
       <para>
        When a script tries to open a file with, for example,
        <function>fopen</function> or <function>gzopen</function>,
        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.
       </para>
       <para>
        The special value <systemitem class="constant">.</systemitem>
        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 <function>chdir</function>.
       </para>
       <para>
        In <filename>httpd.conf</filename>, open_basedir can be turned off
        (e.g. for some virtual hosts)
        <link linkend="configuration.changes.apache">the same way</link> as
        any other configuration directive with "php_admin_value open_basedir
        none".
       </para>
       <para>
        Under Windows, separate the directories with a semicolon. On all
        other systems, separate the directories with a colon. As an Apache
        module, open_basedir paths from parent directories are now
        automatically inherited.
       </para>
       <para>
         The restriction specified with open_basedir is actually a
         prefix, not a directory name.  This means that "open_basedir =
         /dir/incl" also allows access to "/dir/include" and
         "/dir/incls" if they exist. When you want to restrict access
         to only the specified directory, end with a slash. For example:
         "open_basedir = /dir/incl/"
       </para>
       <note>
        <para>
         Support for multiple directories was added in 3.0.7.
        </para>
       </note>
       <para>
        The default is to allow all files to be opened.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.disable-functions">
      <term>
       <parameter>disable_functions</parameter>
       <type>string</type>
      </term>
      <listitem>
       <simpara>
        This directive allows you to disable certain functions for 
        <link linkend="security">security</link> reasons. It takes 
        on a comma-delimited list of function names. disable_functions
        is not affected by <link linkend="ini.safe-mode">Safe Mode</link>.
       </simpara>
       <simpara>
        This directive must be set in &php.ini; For example, you 
        cannot set this in &httpd.conf;.
       </simpara>
      </listitem>
     </varlistentry>
     <varlistentry id="ini.disable-classes">
      <term>
       <parameter>disable_classes</parameter>
       <type>string</type>
      </term>
      <listitem>
       <simpara>
        This directive allows you to disable certain classes for
        <link linkend="security">security</link> reasons.  It takes
        on a comma-delimited list of class names.  disable_classes
        is not affected by <link linkend="ini.safe-mode">Safe Mode</link>.
       </simpara>
       <simpara>
        This directive must be set in &php.ini;  For example, you
        cannot set this in &httpd.conf;.
       </simpara>
       <note>
        <title>Availability note</title>
        <simpara>
         This directive became available in PHP 4.3.2
        </simpara>
       </note>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    See also: <link linkend="ini.register-globals">register_globals</link>,
    <link linkend="ini.display-errors">display_errors</link>, and
    <link linkend="ini.log-errors">log_errors</link>.
   </para>

  <para>
   When <link linkend="ini.safe-mode">safe_mode</link> 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: 
   <programlisting role="ls">
<![CDATA[
-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 
]]>
   </programlisting>
   Running this script.php 
   <programlisting role="php">
<![CDATA[
<?php
 readfile('/etc/passwd'); 
?>
]]>
   </programlisting>
   results in this error when safe mode is enabled: 
   <screen>
<![CDATA[
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
]]>
   </screen>
  </para>
  <para>
   However, there may be environments where a strict <literal>UID</literal>
   check is not appropriate and a relaxed <literal>GID</literal> check is
   sufficient.  This is supported by means of the <link
   linkend="ini.safe-mode-gid">safe_mode_gid</link> switch. Setting it to
   <literal>On</literal> performs the relaxed <literal>GID</literal> checking,
   setting it to <literal>Off</literal> (the default) performs
   <literal>UID</literal> checking.
  </para>
  <para>
   If instead of <link linkend="ini.safe-mode">safe_mode</link>, you set an 
   <link linkend="ini.open-basedir">open_basedir</link> directory then all
   file operations will be limited to files under the specified directory.
   For example (Apache &httpd.conf; example): 
   <programlisting role="ini">
<![CDATA[
<Directory /docroot>
  php_admin_value open_basedir /docroot 
</Directory>
]]>
   </programlisting>
   If you run the same script.php with this
   <link linkend="ini.open-basedir">open_basedir</link> setting
   then this is the result: 
   <screen>
<![CDATA[
Warning: open_basedir restriction in effect. File is in wrong directory in 
/docroot/script.php on line 2 
]]>
   </screen>
  </para>
  <para>
   You can also disable individual functions. Note that the
   <link linkend="ini.disable-functions">disable_functions</link>
   directive can not be used outside of the &php.ini; file which means that
   you cannot disable functions on a per-virtualhost or per-directory basis
   in your &httpd.conf; file.
   If we add this to our &php.ini; file: 
   <programlisting role="ini">
<![CDATA[
disable_functions readfile,system  
]]>
   </programlisting>
   Then we get this output: 
   <screen>
<![CDATA[
Warning: readfile() has been disabled for security reasons in 
/docroot/script.php on line 2 
]]>
   </screen>
  </para>
  <warning>
   <para>
    These PHP restrictions are not valid in executed binaries, of course.
   </para>
  </warning>
 </sect1>

  <sect1 id="features.safe-mode.functions">
   <title>Functions restricted/disabled by safe mode</title>
   <para>
    This is a still probably incomplete and possibly incorrect listing
    of the functions limited by 
    <link linkend="features.safe-mode">safe mode</link>.
    <!-- TODO: add &note.sm.*; to the functions mentioned here.
    That entity should link to this section -->
    <table>
     <title>Safe mode limited functions</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Function</entry>
        <entry>Limitations</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><function>dbmopen</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>dbase_open</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>filepro</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>filepro_rowcount</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>filepro_retrieve</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry>ifx_*</entry>
        <entry>sql_safe_mode restrictions, (!= safe mode)</entry>
        <!-- TODO: more info on sql-safe-mode -->
       </row>
       <row>
        <entry>ingres_*</entry>
        <entry>sql_safe_mode restrictions, (!= safe mode)</entry>
        <!-- TODO: more info on sql-safe-mode -->
       </row>
       <row>
        <entry>mysql_*</entry>
        <entry>sql_safe_mode restrictions, (!= safe mode)</entry>
        <!-- TODO: more info on sql-safe-mode -->
       </row>
       <row>
        <entry><function>pg_lo_import</function></entry>
        <entry>&sm.uidcheck;</entry>
        <!-- source TODO: there is no PHP-warning for that safe-mode-restriction -->
       </row>
       <row>
        <entry><function>posix_mkfifo</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>putenv</function></entry>
        <entry>Obeys the safe_mode_protected_env_vars and 
        safe_mode_allowed_env_vars ini-directives. See also the documentation
        on <function>putenv</function></entry>
        <!-- TODO: document those directives in chapters/config.xml -->
       </row>
       <row>
        <entry><function>move_uploaded_file</function></entry>
        <entry>&sm.uidcheck; <!-- TODO: check this --></entry>
       </row>

       <!-- TODO: from here on, add warning to the function itself -->

       <row>
        <entry><function>chdir</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>dl</function></entry>
        <entry>&sm.disabled;</entry>
       </row>
       <row>
        <entry><link linkend="language.operators.execution">backtick operator</link></entry>
        <entry>&sm.disabled;</entry>
       </row>
       <row>
        <entry><function>shell_exec</function> (functional equivalent 
        of backticks)</entry>
        <entry>&sm.disabled;</entry>
       </row>
       <row>
        <entry><function>exec</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.
        <function>escapeshellcmd</function> is executed on the argument of this
        function.</entry>
       </row>
       <row>
        <entry><function>system</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.
        <function>escapeshellcmd</function> is executed on the argument of this
        function.</entry>
       </row>
       <row>
        <entry><function>passthru</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.
        <function>escapeshellcmd</function> is executed on the argument of this
        function.</entry>
       </row>
       <row>
        <entry><function>popen</function></entry>
        <entry>You can only execute executables within the <link 
        linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
        For practical reasons it's currently not allowed to have
        <literal>..</literal> components in the path to the executable.
        <function>escapeshellcmd</function> is executed on the argument of this
        function.</entry>
        <!-- TODO: not sure. popen uses a completely different implementation
        Don't know why, don't know whether it's behaving the same -->
       </row>
       <row>
        <entry><function>fopen</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>mkdir</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>rmdir</function></entry>
        <entry>&sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>rename</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir;<!-- on the old name only, it seems. Is rename preventing moving files? --></entry>
       </row>
       <row>
        <entry><function>unlink</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>copy</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir; (on 
        <parameter>source</parameter> and 
        <parameter>target</parameter>) </entry>
       </row>
       <row>
        <entry><function>chgrp</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>chown</function></entry>
        <entry>&sm.uidcheck;</entry>
       </row>
       <row>
        <entry><function>chmod</function></entry>
        <entry>&sm.uidcheck; In addition, you cannot  
        set the SUID, SGID and sticky bits</entry>
       </row>
       <row>
        <entry><function>touch</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir;</entry>
       </row>
       <row>
        <entry><function>symlink</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir; (note: only the target is 
        checked)</entry>
       </row>
       <row>
        <entry><function>link</function></entry>
        <entry>&sm.uidcheck; &sm.uidcheck.dir; (note: only the target is 
        checked)</entry>
       </row>
       <row>
        <entry><function>apache_request_headers</function></entry>
        <entry>In safe mode, headers beginning with 'authorization' 
        (case-insensitive) will not be returned.</entry>
       </row>
       <row>
        <entry><function>header</function></entry>
        <entry>In safe mode, the uid of the script is added to the
        <literal>realm</literal> part of the
        <literal>WWW-Authenticate</literal> header if you set this
        header (used for HTTP Authentication).</entry>
       </row>
       <row>
        <entry><link linkend="features.http-auth">PHP_AUTH variables</link></entry>
        <entry>
         In safe mode, the variables <varname>PHP_AUTH_USER</varname>,
         <varname>PHP_AUTH_PW</varname>, and <varname>AUTH_TYPE</varname>
         are not available in <varname>$_SERVER</varname>. Regardless, you
         can still use <varname>REMOTE_USER</varname> for the USER.
         (note: only affected since PHP 4.3.0)
        </entry>
       </row>
       <row>
        <entry>
         <function>highlight_file</function>,
         <function>show_source</function>
        </entry>
        <entry>
         &sm.uidcheck; &sm.uidcheck.dir; (note: only affected since PHP 4.2.1)
        </entry>
       </row>
       <row>
        <entry>
         <function>parse_ini_file</function>
        </entry>
        <entry>
         &sm.uidcheck; &sm.uidcheck.dir; (note: only affected since PHP 4.2.1)
        </entry>
       </row>
       <row>
        <entry>
         <function>set_time_limit</function>
        </entry>
        <entry>
         Has no effect when PHP is running in &safemode;.
        </entry>
       </row>
       <row>
        <entry>
         <link linkend="ini.max-execution-time">max_execution_time</link>
        </entry>
        <entry>
         Has no effect when PHP is running in &safemode;.
        </entry>
       </row>
       <row>
        <entry>
         <function>mail</function>
        </entry>
        <entry>
         In safe mode, the fifth parameter is disabled. (note: only affected since PHP 4.2.3)
        </entry>
       </row>
       <row>
        <entry>Any function that uses
         <filename>php4/main/fopen_wrappers.c</filename>
        </entry>
        <entry>??</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </sect1>

 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->