Source of: /manual/en/security.cgi-bin.doc-root.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/security.cgi-bin.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'security.cgi-bin.doc-root.php',
1 => 'Case 3: setting doc_root or user_dir',
),
'up' =>
array (
0 => 'security.cgi-bin.php',
1 => 'Installed as CGI binary',
),
'prev' =>
array (
0 => 'security.cgi-bin.force-redirect.php',
1 => 'Case 2: using cgi.force_redirect',
),
'next' =>
array (
0 => 'security.cgi-bin.shell.php',
1 => 'Case 4: PHP parser outside of web tree',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="security.cgi-bin.doc-root" class="sect1">
<h2 class="title">Case 3: setting doc_root or user_dir</h2>
<p class="simpara">
To include active content, like scripts and executables, in the
web server document directories is sometimes considered an insecure
practice. If, because of some configuration mistake, the scripts
are not executed but displayed as regular HTML documents, this
may result in leakage of intellectual property or security
information like passwords. Therefore many sysadmins will prefer
setting up another directory structure for scripts that are
accessible only through the PHP CGI, and therefore always
interpreted and not displayed as such.
</p>
<p class="simpara">
Also if the method for making sure the requests are not
redirected, as described in the previous section, is not
available, it is necessary to set up a script doc_root that is
different from web document root.
</p>
<p class="simpara">
You can set the PHP script document root by the configuration
directive <a href="ini.core.php#ini.doc-root" class="link">doc_root</a> in the
<a href="configuration.file.php" class="link">configuration file</a>, or
you can set the environment variable
<span class="envar">PHP_DOCUMENT_ROOT</span>. If it is set, the <acronym title="Common Gateway Interface">CGI</acronym>
version of PHP will always construct the file name to open with this
<i><tt class="parameter">doc_root</tt></i>
and the path information in the
request, so you can be sure no script is executed outside this
directory (except for <i><tt class="parameter">user_dir</tt></i>
below).
</p>
<p class="simpara">
Another option usable here is <a href="ini.core.php#ini.user-dir" class="link">user_dir</a>. When user_dir is unset,
only thing controlling the opened file name is
<i><tt class="parameter">doc_root</tt></i>
. Opening a URL like <var class="filename">http://my.host/~user/doc.php</var> does not
result in opening a file under users home directory, but a file
called <var class="filename">~user/doc.php</var> under
doc_root (yes, a directory name starting with a tilde
[<i>~</i>]).
</p>
<p class="simpara">
If user_dir is set to for example <var class="filename">public_php</var>, a request like <var class="filename">http://my.host/~user/doc.php</var> will open a
file called <var class="filename">doc.php</var> under the directory
named <var class="filename">public_php</var> under the home
directory of the user. If the home of the user is <var class="filename">/home/user</var>, the file executed is
<var class="filename">/home/user/public_php/doc.php</var>.
</p>
<p class="simpara">
<i><tt class="parameter">user_dir</tt></i>
expansion happens regardless of
the <i><tt class="parameter">doc_root</tt></i>
setting, so you can control
the document root and user directory access
separately.
</p>
</div><?php manual_footer(); ?>
