<chapter id="configuration">
  <title>Configuration</title>
   <simpara>

  <sect1 id="php3.ini">
   <title>The php3.ini file</title>
   <simpara>
    The <filename>php3.ini</filename> file is read when PHP's parser
    starts up.  For the server module versions of PHP, this happens
    only once when the web server is started.  For the
    <acronym>CGI</acronym> version, it happens on every invocation.
   </simpara>
   <simpara>
    Just about every directive listed here has a corresponding Apache 
    <filename>httpd.conf</filename> directive.  Simply prepend 
    <emphasis>php3_</emphasis> to the start of the directive names listed
    here.
   </simpara>
   
   <sect2 id="ini.sect.general">
    <title>General Configuration Directives</title>
    <para>
     <variablelist>
      
      <varlistentry id="ini.auto-append-file">
       <term>
	<parameter>auto_append_file</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 Specifies the name of a file that is automatically parsed
	 after the main file.  The file is included as if it was
	 called with the <function>include</function> function, so
	 <link linkend="ini.include-path">include_path</link> is used.
	<para>
	 The special value <systemitem
	  class="constant">none</systemitem> disables auto-appending.
	 <note>
	  <simpara>
	   If the script is terminated with <function>exit</function>,
	   auto-append will <emphasis>not</emphasis> occur.
	 </note>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.auto-prepend-file">
       <term>
	<parameter>auto_prepend_file</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 Specifies the name of a file that is automatically parsed
	 before the main file.  The file is included as if it was
	 called with the <function>include</function> function, so
	 <link linkend="ini.include-path">include_path</link> is used.
	<para>
	 The special value <systemitem
	 class="constant">none</systemitem> disables auto-prepending.
       </listitem>
      </varlistentry>

      <varlistentry id="ini.cgi-ext">
       <term>
	<parameter>cgi_ext</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.display-errors">
       <term>
	<parameter>display_errors</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 This determines whether errors should be printed to the screen
	 as part of the HTML output or not.
	</para>
       </listitem>
      </varlistentry>
      
      <varlistentry id="ini.doc-root">
       <term>
	<parameter>doc_root</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 PHP's "root directory" on the server.  Only used if non-empty.  If
	 PHP is configured with <link linkend="ini.safe-mode">safe
	 mode</link>, no files outside this directory are served.
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.engine">
       <term>
	<parameter>engine</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 This directive is really only useful in the Apache module version
	 of PHP.  It is used by sites that would like to turn PHP parsing on
	 and off on a per-directory or per-virtual server basis.  By putting
	 <userinput>php3_engine off</userinput> in the appropriate places in
	 the <filename>httpd.conf</filename> file, PHP can be enabled or
	 disabled.
	</para>
       </listitem>
      </varlistentry>
      
      <varlistentry id="ini.error-log">
       <term>
	<parameter>error_log</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 Name of file where script errors should be logged.  If the special
	 value <literal>syslog</literal> is used, the errors are sent to the
	 system logger instead.  On UNIX, this means syslog(3) and on
	 Windows NT it means the event log.  The system logger is not
	 supported on Windows 95.
       </listitem>
      </varlistentry>

      <varlistentry id="ini.error-reporting">
       <term>
	<parameter>error_reporting</parameter>
	<type>integer</type>
       </term>
       <listitem>
	<para>
	 Set the error reporting level.  The parameter is an integer
	 representing a bit field.  Add the values of the error
	 reporting levels you want.
	 <table>
	  <title>Error Reporting Levels</title>
	  <tgroup cols="2">
	   <thead>
	    <row>
	     <entry>bit value</entry>
	     <entry>enabled reporting</entry>
	    </row>
	   </thead>
	   <tbody>
	    <row>
	     <entry>1</entry>
	     <entry>normal errors</entry>
	    </row>
	    <row>
	     <entry>2</entry>
	     <entry>normal warnings</entry>
	    </row>
	    <row>
	     <entry>4</entry>
	     <entry>parser errors</entry>
	    </row>
	    <row>
	     <entry>8</entry>
	     <entry>non-critical style-related warnings</entry>
	    </row>
	   </tbody>
	  </tgroup>
	 </table>
	 The default value for this directive is 7 (normal errors, normal
	 warnings and parser errors are shown).
	</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.
	</para>
	<para>
	 When a script tries to open a file with,
	 for example, fopen or gzopen, 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 directory in which the script is stored will
	 be used as base-directory.
	</para>
	<para>
	 The default is to allow all files to be opened.
	</para>
       </listitem>
      </varlistentry>
      
      <varlistentry id="ini.gpc-order">
       <term>
	<parameter>gpc_order</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 Set the order of GET/POST/COOKIE variable parsing.  The
	 default setting of this directive is "GPC".  Setting this to
	 "GP", for example, will cause PHP to completely ignore cookies
	 and to overwrite any GET method variables with POST-method
	 variables of the same name.
	</para>
       </listitem>
      </varlistentry>
      
      <varlistentry id="ini.include-path">
       <term>
	<parameter>include_path</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 Specifies a list of directories where the
	 <function>require</function>, <function>include</function> and
	 <function>fopen_with_path</function> functions look for files.  The
	 format is like the system's <envar>PATH</envar> environment
	 variable: a list of directories separated with a colon in UNIX or
	 semicolon in Windows.
	 <example>
	  <title>UNIX include_path</title>
	  <programlisting role=php3.ini>
include_path=.:/home/httpd/php-lib
</programlisting>
	 </example>
	 <example>
	  <title>Windows include_path</title>
	  <programlisting role=php3.ini>
include_path=.;c:\www\phplib
</programlisting>
	 </example>
	 The default value for this directive is <literal>.</literal> (only
	 the current directory).
       </listitem>
      </varlistentry>

      <varlistentry id="ini.isapi-ext">
       <term>
	<parameter>isapi_ext</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.log-errors">
       <term>
	<parameter>log_errors</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 Tells whether script error messages should be logged to the
	 server's error log.  This option is thus server-specific.
       </listitem>
      </varlistentry>

      <varlistentry id="ini.magic-quotes-gpc">
       <term>
	<parameter>magic_quotes_gpc</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 Sets the magic_quotes state for GPC (Get/Post/Cookie) operations.  
	 When magic_quotes are on, all ' (single-quote), &quot; (double quote),
	 \ (backslash) and NUL's are escaped with a backslash automatically.
	 If magic_quotes_sybase is also on, a single-quote is escaped with a
	 single-quote instead of a backslash.  
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.magic-quotes-runtime">
       <term>
	<parameter>magic_quotes_runtime</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 If magic_quotes_runtime is enabled, most functions that return data
	 from any sort of external source including databases and text files
	 will have quotes escaped with a backslash.
	 If magic_quotes_sybase is also on, a single-quote is escaped with a
     single-quote instead of a backslash.
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.magic-quotes-sybase">
       <term>
	<parameter>magic_quotes_sybase</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
     If magic_quotes_sybase is also on, a single-quote is escaped with a
     single-quote instead of a backslash if magic_quotes_gpc or magic_quotes_runtime
	 is enabled.
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.max-execution-time">
       <term>
	<parameter>max_execution_time</parameter>
	<type>integer</type>
       </term>
       <listitem>
	<para>
	 This sets the maximum time in seconds a script is allowed to
	 take before it is terminated by the parser.  This helps
	 prevent poorly written scripts from tieing up the server.
	</para>
       </listitem>
      </varlistentry>
      
      <varlistentry id="ini.memory-limit">
       <term>
	<parameter>memory_limit</parameter>
	<type>integer</type>
       </term>
       <listitem>
	<para>
	 This sets the maximum amount of memory in bytes that a script
	 is allowed to allocate.  This helps prevent poorly written
	 scripts for eating up all available memory on a server.
	</para>
       </listitem>
      </varlistentry>
      
      <varlistentry id="ini.nsapi-ext">
       <term>
	<parameter>nsapi_ext</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.short-open-tag">
       <term>
	<parameter>short_open_tag</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 Tells whether the short form (<userinput>&lt? ?></userinput>of
	 PHP's open tag should be allowed.  If you want to use PHP in
	 combination with XML, you have to disable this option.  If
	 disabled, you must use the long form of the open tag
	 (<userinput>&lt;?php ?></userinput>).
       </listitem>
      </varlistentry>

      <varlistentry id="ini.sql.safe-mode">
       <term>
	<parameter>sql.safe_mode</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	</para>
       </listitem>
      </varlistentry>

      <varlistentry id="ini.track-errors">
       <term>
	<parameter>track_errors</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 If enabled, the last error message will always be present in the
	 global variable <symbol>$php_errormsg</symbol>.
       </listitem>
      </varlistentry>

      <varlistentry id="ini.track-vars">
       <term>
	<parameter>track_vars</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 If enabled, GET, POST and cookie input can be found in the global
	 associative arrays <symbol>$HTTP_GET_VARS</symbol>,
	 <symbol>$HTTP_POST_VARS</symbol> and
	 <symbol>$HTTP_COOKIE_VARS</symbol>, respectively.
       </listitem>
      </varlistentry>

      <varlistentry id="ini.upload-tmp-dir">
       <term>
	<parameter>upload_tmp_dir</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 The temporary directory used for storing files when doing file
	 upload.  Must be writable by whatever user PHP is running as.
       </listitem>
      </varlistentry>

      <varlistentry id="ini.user-dir">
       <term>
	<parameter>user_dir</parameter>
	<type>string</type>
       </term>
       <listitem>
	<para>
	 The base name of the directory used on a user's home directory for
	 PHP files, for example <literal>public_html</literal>.
       </listitem>
      </varlistentry>

      <varlistentry id="ini.warn-plus-overloading">
       <term>
	<parameter>warn_plus_overloading</parameter>
	<type>boolean</type>
       </term>
       <listitem>
	<para>
	 If enabled, this option makes PHP output a warning when the plus
	 (<literal>+</literal>) operator is used on strings.  This is to
	 make it easier to find scripts that need to be rewritten to using
	 the string concatenator instead (<literal>.</literal>).
       </listitem>
      </varlistentry>

     </variablelist>
    </para>
   </sect2>

   <sect2 id="ini.sect.mail">
    <title>Mail Configuration Directives</title>
    <variablelist>

     <varlistentry id="ini.smtp">
      <term>
       <parameter>SMTP</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	DNS name or IP address of the SMTP server PHP under Windows should
	use for mail sent with the <function>mail</function> function.
      </listitem>
     </varlistentry>

     <varlistentry id="ini.sendmail-from">
      <term>
       <parameter>sendmail_from</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	Which "From:" mail address should be used in mail sent from PHP
	under Windows.
      </listitem>
     </varlistentry>

     <varlistentry id="ini.sendmail-path">
      <term>
       <parameter>sendmail_path</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	Where the <command>sendmail</command> program can be found, usually
	<filename>/usr/sbin/sendmail</filename> or
	<filename>/usr/lib/sendmail</filename> <command>configure</command>
	does an honest attempt of locating this one for you and set a
	default, but if it fails, you can set it here.
       <para>
	Systems not using sendmail should set this directive to the sendmail
	wrapper/replacement their mail system offers, if any.  For example,
	<ulink url="http://www.qmail.org/">Qmail</ulink> users can normally
	set it to <filename>/var/qmail/bin/sendmail</filename>.
      </listitem>
     </varlistentry>

    </variablelist>
   </sect2>

   <sect2 id="ini.sect.safe-mode">
    <title>Safe Mode Configuration Directives</title>
    <variablelist>

     <varlistentry id="ini.safe-mode">
      <term>
       <parameter>safe_mode</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether to enable PHP's safe mode.
      </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 functions executing system programs refuse to start programs
	that are not in this directory.
      </listitem>
     </varlistentry>

    </variablelist>
   </sect2>

   <sect2 id="ini.sect.debugger">
    <title>Debugger Configuration Directives</title>
    <variablelist>

     <varlistentry id="ini.debugger.host">
      <term>
       <parameter>debugger.host</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	DNS name or IP address of host used by the debugger.
      </listitem>
     </varlistentry>

     <varlistentry id="ini.debugger.port">
      <term>
       <parameter>debugger.port</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	Port number used by the debugger.
      </listitem>
     </varlistentry>

     <varlistentry id="ini.debugger.enabled">
      <term>
       <parameter>debugger.enabled</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether the debugger is enabled.
      </listitem>
     </varlistentry>

    </variablelist>
   </sect2>

   <sect2 id="ini.sect.extension">
    <title>Extension Loading Directives</title>
    <variablelist>
     
     <varlistentry id="ini.enable-dl">
      <term>
	<parameter>enable_dl</parameter>
	<type>boolean</type>
      </term>
      <listitem>
	<para>
	 This directive is really only useful in the Apache module
	 version of PHP. You can turn dynamic loading of PHP
	 extensions with <function>dl</function> on and off per
	 virtual server or per directory.
	</para>
	<para>
	 The main reason for turning dynamic loading off is security. With
	 dynamic loading, it's possible to ignore all the safe_mode and
	 open_basedir restrictions.
	</para>
	<para>
	 The default is to allow dynamic loading, except when using
	 safe-mode.  In safe-mode, it's always imposible to use
	 <function>dl</function>.
	</para>
      </listitem>
     </varlistentry>
      
     <varlistentry id="ini.extension-dir">
      <term>
       <parameter>extension_dir</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	In what directory PHP should look for dynamically loadable
	extensions.
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.extension">
      <term>
       <parameter>extension</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	Which dynamically loadable extensions to load when PHP starts up.
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.mysql">
    <title>MySQL Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.mysql.allow-persistent">
      <term>
       <parameter>mysql.allow_persistent</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether to allow persistent MySQL connections.
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.mysql.max-persistent">
      <term>
       <parameter>mysql.max_persistent</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of persistent MySQL connections per process.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.mysql.max-links">
      <term>
       <parameter>mysql.max_links</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of MySQL connections per process, including
	persistent connections.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.msql">
    <title>mSQL Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.msql.allow-persistent">
      <term>
       <parameter>msql.allow_persistent</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether to allow persistent mSQL connections.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.msql.max-persistent">
      <term>
       <parameter>msql.max_persistent</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of persistent mSQL connections per process.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.msql.max-links">
      <term>
       <parameter>msql.max_links</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of mSQL connections per process, including
	persistent connections.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.pgsql">
    <title>Postgres Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.pgsql.allow-persistent">
      <term>
       <parameter>pgsql.allow_persistent</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether to allow persistent Postgres connections.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.pgsql.max-persistent">
      <term>
       <parameter>pgsql.max_persistent</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of persistent Postgres connections per process.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.pgsql.max-links">
      <term>
       <parameter>pgsql.max_links</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of Postgres connections per process, including
	persistent connections.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.sybase">
    <title>Sybase Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.sybase.allow-persistent">
      <term>
       <parameter>sybase.allow_persistent</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether to allow persistent Sybase connections.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.sybase.max-persistent">
      <term>
       <parameter>sybase.max_persistent</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of persistent Sybase connections per process.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.sybase.max-links">
      <term>
       <parameter>sybase.max_links</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of Sybase connections per process, including
	persistent connections.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.sybct">
    <title>Sybase-CT Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.sybct.allow-persistent">
      <term>
       <parameter>sybct.allow_persistent</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether to allow persistent Sybase-CT connections.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.sybct.max-persistent">
      <term>
       <parameter>sybct.max_persistent</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of persistent Sybase-CT connections per process.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.sybct.max-links">
      <term>
       <parameter>sybct.max_links</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of Sybase-CT connections per process, including
	persistent connections.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.bcmath">
    <title>BC Math Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.bcmath.scale">
      <term>
       <parameter>bcmath.scale</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	Number of decimal digits for all bcmath functions.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.browscap">
    <title>Browser Capability Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.browscap">
      <term>
       <parameter>browscap</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	Name of browser capabilities file.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

   <sect2 id="ini.sect.uodbc">
    <title>Unified ODBC Configuration Directives</title>
    <variablelist>
     
     <varlistentry id="ini.uodbc.default-db">
      <term>
       <parameter>uodbc.default_db</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	ODBC data source to use if none is specified in
	<function>odbc_connect</function> or
	<function>odbc_pconnect</function>.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.uodbc.default-user">
      <term>
       <parameter>uodbc.default_user</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	User name to use if none is specified in
	<function>odbc_connect</function> or
	<function>odbc_pconnect</function>.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.uodbc.default-pw">
      <term>
       <parameter>uodbc.default_pw</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
	Password to use if none is specified in
	<function>odbc_connect</function> or
	<function>odbc_pconnect</function>.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.uodbc.allow-persistent">
      <term>
       <parameter>uodbc.allow_persistent</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
	Whether to allow persistent ODBC connections.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.uodbc.max-persistent">
      <term>
       <parameter>uodbc.max_persistent</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of persistent ODBC connections per process.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.uodbc.max-links">
      <term>
       <parameter>uodbc.max_links</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
	The maximum number of ODBC connections per process, including
	persistent connections.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
   </sect2>

  </sect1>

  <sect1 id="config-apache">
   <title>Apache Module</title>
   
   <sect2 id="config-apache-module">
    <title>Apache module configuration directives</title>
    <simpara></simpara>

   <sect2 id="config-apache-action">
    <title>CGI redirection module/action module</title>
    <simpara></simpara>

  <sect1 id="config-cgi">
   <title>CGI</title>
   <simpara></simpara>

  <sect1 id="config-virtualhost">
   <title>Virtual hosts</title>
   <simpara></simpara>

  <sect1 id="config-security">
   <title>Security</title>
   <simpara>
    PHP is a powerful language and the interpreter, whether included
    in a web server as a module or executed as a separate
    <acronym>CGI</acronym> binary, is able to access files, execute
    commands and open network connections on the server.  These
    properties make anything run on a web server insecure by default.
    PHP is designed specifically to be a more secure language for
    writing CGI programs than Perl or C, and with correct selection of
    compile-time and runtime configuration options it gives you
    exactly the combination of freedom and security you need.

   <simpara>
    As there are many different ways of utilizing PHP, there are many
    configuration options controlling its behaviour.  A large
    selection of options guarantees you can use PHP for a lot of
    purposes, but it also means there are combinations of these
    options and server configurations that result in an insecure
    setup.  This chapter explains the different configuration option
    combinations and the situations they can be safely used.

   <sect2 id="config-security-cgi">
    <title>CGI binary</title>

    <sect3 id="config-security-cgi-preface">
     <title>Possible attacks</title>

     <simpara>
      Using PHP as a <acronym>CGI</acronym> binary is an option for
      setups that for some reason do not wish to integrate PHP as a
      module into server software (like Apache), or will use PHP with
      different kinds of CGI wrappers to create safe chroot and setuid
      environments for scripts.  This setup usually involves
      installing executable PHP binary to the web server cgi-bin
      directory.  CERT advisory <ulink
      url="http://www.cert.org/pub/advisories/CA-96.11.interpreters_in_cgi_bin_dir.html">CA-96.11</ulink>
      recommends agains placing any interpreters into cgi-bin.  Even
      if the PHP binary can be used as a standalone interpreter, PHP
      is designed to prevent the attacks this setup makes possible:

     <itemizedlist>
      <listitem><simpara>Accessing system files:
        <filename role=url>http://my.host/cgi-bin/php?/etc/passwd</filename>

       <simpara>
        The query information in an url after the question mark (?)
	is passed as command line arguments to the interpreter by the
	CGI interface.  Usually interpreters open and execute the
	file specified as the first argument on the command line.

       <simpara>
        When invoked as a CGI binary, PHP refuses to interpret the
	command	line arguments.
       </simpara></listitem>
      <listitem><simpara>Accessing any web document on server:
	<filename
	 role=url>http://my.host/cgi-bin/php/secret/doc.html</filename>

       <simpara>
	The path information part of the url after the PHP binary
	name, <filename role=uri>/secret/doc.html</filename> is
	conventionally used to specify the name of the file to be
	opened and interpreted by the <acronym>CGI</acronym> program.
	Usually some web server configuration directives (Apache:
	Action) are used to redirect requests to documents like
	<filename
	role=url>http://my.host/secret/script.php3</filename> to the
	PHP interpreter.  With this setup, the web server first checks
	the access permissions to the directory <filename
	role=uri>/secret</filename>, and after that creates the
	redirected request <filename
	role=url>http://my.host/cgi-bin/php/secret/script.php3</filename>.
	Unfortunately, if the request is originally given in this
	form, no access checks are made by web server for file
	<filename role=uri>/secret/script.php3</filename>, but only
	for the <filename role=uri>/cgi-bin/php</filename> file.  This
	way any user able to access <filename
	role=uri>/cgi-bin/php</filename> is able to access any
	protected document on the web server.

       <simpara>
	In PHP, compile-time configuration option <link
	 linkend="enable-force-cgi-redirect">--enable-force-cgi-redirect</link>
	and runtime configuration directives <link
	 linkend="ini.doc-root">doc_root</link> and <link
	 linkend="ini.user-dir">user_dir</link> can be used to prevent
	this attack, if the server document tree has any directories
	with access restrictions.  See below for full explanation of
	different combinations.

       </simpara></listitem>
     </itemizedlist>

    </sect3>
      

    <sect3 id="config-security-cgi-public">
     <title>Case 1: only public files served</title>
     <simpara>
      If your server does not have any content that is not restricted
      by password or ip based access control, there is no need for
      these configuration options.  If your web server does not allow
      you to do redirects, or the server does not have a way to
      communicate with the PHP binary that the request is a safely
      redirected request, you can specify the option <link
      linkend="enable-force-cgi-redirect">--disable-force-cgi-redirect</link>
      to the configure script.  You still have to make sure your PHP
      scripts do not rely on one or another way of calling the script,
      neither by directly <filename
      role=php>http://my.host/cgi-bin/php/dir/script.php3</filename>
      nor by redirection <filename
      role=php>http://my.host/dir/script.php3</filename>.

     <simpara>
      Redirection can be configured for example in apache by
      directives AddHandler and Action (see below).
    </sect3>
      
    <sect3 id="config-security-cgi-force">
     <title>Case 2: using --enable-force-cgi-redirect</title>
     <simpara>
      This compile-time option prevents anyone from calling PHP directly 
      with a url like <filename role=php>http://my.host/cgi-bin/php/secretdir/script.php3</filename>.
      Instead, PHP will only parse in this mode if it has gone through 
      a web server redirect rule. 
     <simpara>
      Usually the redirection in the Apache configuration is done with
      the following directives: <programlisting role="apache-conf">
Action php3-script /cgi-bin/php
AddHandler php3-script .php3
</programlisting>

     <simpara>
      This option has only been tested with the Apache web server, and relies on
      Apache to set the non-standard CGI environment variable
      <envar>REDIRECT_STATUS</envar> on redirected requests.  If your
      web server does not support any way of telling if the request is
      direct or redirected, you cannot use this option and you must
      use one of the other ways of running the CGI version documented here.
    </sect3>
      
    <sect3 id="config-security-cgi-docroot">
     <title>Case 3: setting doc_root or user_dir</title>
     <simpara>
      To include active content, like scripts and executables, in the
      web server document directories is sometimes consider an
      insecure practice.  If for some configuration mistake the
      scripts are not executed but displayed as usual 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
      is only accessible through the PHP CGI, and therefore always
      interpreted and not displayed as such.
      
     <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.
      
     <simpara>
      You can set the PHP script document root by the configuration
      directive <link linkend="ini.doc-root">doc_root</link> in the
      <link linkend="php3.ini">php3.ini</link> file, or you can set
      the environment variable <envar>PHP_DOCUMENT_ROOT</envar>.  If
      it is set, the CGI version of PHP will always construct the file
      name to open with this <parameter>doc_root</parameter> and the
      path information in the request, so you can be sure no script is
      executed outside this directory (except for
      <parameter>user_dir</parameter> below).
      
     <simpara>
      Another option usable here is <link
      linkend="ini.user-dir">user_dir</link>.  When user_dir is unset,
      only thing controlling the opened file name is
      <parameter>doc_root</parameter>.  Opening an url like <filename
      role=url>http://my.host/~user/doc.php3</filename> does not
      result in opening a file under users home directory, but a file
      called <filename role=uri>~user/doc.php3</filename> under
      doc_root (yes, a directory name starting with a tilde
      [<literal>~</literal>]).
      
     <simpara>
      If user_dir is set to for example <filename
      role=dir>public_php</filename>, a request like <filename
      role=url>http://my.host/~user/doc.php3</filename> will open a
      file called <filename>doc.php3</filename> under the directory
      named <filename role=dir>public_php</filename> under the home
      directory of the user.  If the home of the user is <filename
      role=dir>/home/user</filename>, the file executed is
      <filename>/home/user/public_php/doc.php3</filename>.
      
     <simpara>
      <parameter>user_dir</parameter> expansion happens regardless of
      the <parameter>doc_root</parameter> setting, so you can control
      the document root and user directory access separately.
      
    </sect3>
    <sect3 id="config-security-cgi-shell">
     <title>Case 4: PHP parser outside of web tree</title>
     <para>
      A very secure option is to put the PHP parser binary somewhere
      outside of the web tree of files.  In <filename
      role=dir>/usr/local/bin</filename>, for example.  The only real
      downside to this option is that you will now have to put a line
      similar to:
      
      <informalexample>
       <programlisting>#!/usr/local/bin/php</programlisting>
      </informalexample>
	
      as the first line of any file containing PHP tags.  You will
      also need to make the file executable.  That is, treat it
      exactly as you would treat any other CGI script written in Perl
      or sh or any other common scripting language which uses the
      <literal>#!</literal> shell-escape mechanism for launching
      itself.
     <para>
      To get PHP to handle <envar>PATH_INFO</envar> and
      <envar>PATH_TRANSLATED</envar> information correctly with this
      setup, the php parser should be compiled with the <link
      linkend="enable-discard-path">--enable-discard-path</link>
      configure option.
    </sect3>
   </sect2>
   
   <sect2 id="config-security-apache">
    <title>Apache module</title>
    <simpara>
   	When PHP is used as an Apache module it inherits Apache's security setup.
    A request for a file will have to go through Apache's regular checks and
    only if these are passed successfully does the request make it way to PHP.
    
   </sect2>

 </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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->