doc/CONFIG

   1 ===========================
   2 == suPHP                 ==
   3 ===========================
   4
   5 Configuration
   6 -------------
   7
   8 1. General notes
   9
  10 The suPHP configuration file resides in $sysconfdir/suphp.conf (which will
  11 resolve e.g. to /etc/suphp.conf).
  12
  13 It has the usual "INI-file" syntax.
  14
  15 Section names are encapsulated in square brackets (e.g. [global]).
  16 Configuration options are key value pairs, separated by a "=" sign (e.g.
  17 umask=0077).
  18
  19 Comment lines start with a ";".
  20
  21 You can find a sample configuration in suphp.conf-example
  22
  23
  24 2. Multiple values and escaping
  25
  26 For a setting that allows multiple values, you can either seperate the
  27 values using the colon (":") character or you can use multiple lines.
  28 If you use multiple lines any line following the first has to use the "+="
  29 assignment, otherwise preceding values will be discarded.
  30
  31 If you want to use the ":" character in a value, you have to escape it
  32 using a backslash ("\"). The backslash itself is escaped by prepending
  33 another backslash.
  34
  35 For patterns the asterisk ("*") has to be escaped, too.
  36
  37
  38 3. Variables
  39
  40 Certain configuration values may contain variables. Valid variables are:
  41
  42 ${USERNAME}  - is replaced by the name of the target user
  43 ${UID}       - is replaced by the numerical UID of the target user
  44 ${GROUPNAME} - is replaced by the name of the target group
  45 ${GID}       - is replaced by the numerical GID of the target group
  46 ${HOME}      - is replaced by the path to the home directory of the target user
  47
  48 Dollar ("$") characters that are not meant to represent variables, have to
  49 be escape using a backslash ("\"), if used in a value that allows
  50 variables.
  51
  52
  53 4. Global options
  54
  55 This options have to be specified in the [global] section.
  56 All this options are facultative.
  57
  58 logfile:
  59   Specifies path to logfile. If not specified, the compile-time value is
  60   used.
  61
  62 loglevel:
  63   One of "info", "warn", "error", "none".
  64   Specifies messages of which classification should be logged.
  65   Defaults to "info".
  66
  67 webserver_user:
  68   Username of UID webserver is running as. If not specified, the
  69   compile-time value is used.
  70
  71 docroot:
  72   Patterns matching all allowed script directories. This is an
  73   additional security check, especially when
  74   check_vhost_docroot is disabled. Defaults to "/*" thus
  75   allowing scripts in any location being run. May contain the
  76   "*" character which matches zero to n characters excluding
  77   the "/" character. Multiple values are allowed for this
  78   setting. May contain variables as described above.
  79
  80 chroot:
  81   Path to change the process's root directory to before executing the
  82   script. Has to be specified without a trailing slash.
  83   If not specified, no chroot() call is performed. May contain variables
  84   as described above.
  85
  86 allow_file_group_writeable:
  87   Allow files to be group writeable. Is disabled by default.
  88
  89 allow_directory_group_writeable:
  90   Allow directories scripts are residing in to be group writeable.
  91   Is disabled by default.
  92
  93 allow_file_others_writeable:
  94   Allow files to be writeable by world. Is disabled by default:
  95   WARNING: Enabling this option is very dangerous and causes major
  96   security issues, especially the danger of arbitrary code execution!
  97
  98 allow_directoy_others_writeable:
  99   Allow directories scripts are residing in to be writeable by world.
 100   Is disabled by default:
 101   WARNING: Enabling this option is dangerous!
 102
 103 check_vhost_docroot:
 104   Checks wheter the script is within DOCUMENT_ROOT specified by the
 105   webserver. This option is intended to avoid symbol links outside of the
 106   webpage directory. You may want to disable it, when you are using
 107   mod_vhost_alias or the Alias-directive.
 108   This option is disabled by default, if at compile-time the
 109   "--disable-check-docroot" option has been specified, otherwise it is
 110   enabled by default.
 111
 112 errors_to_browser:
 113   Enable this option to sent information about minor problems during script
 114   invocation to the browser. This option is disabled by default.
 115
 116 env_path:
 117   Content of the "PATH" environment variable. Set this to a secure value.
 118   The default value is "/bin:/usr/bin".
 119
 120 umask:
 121   umask to set before script execution.
 122   Has to be specified in octal notation (e.g. 0077).
 123
 124 min_uid:
 125   Minimum UID allowed to execute scripts.
 126   Defaults to compile-time value.
 127
 128 min_gid:
 129   Minimum GID allowed to execute scripts.
 130   Defaults to compile-time value.
 131
 132
 133 5. Handlers
 134
 135 In the [handlers] section you specify a mapping between mime-types and
 136 interpreters to be used.
 137
 138 Example:
 139 x-httpd-php=php:/usr/bin/php
 140
 141 The "key" is the mime-type. The "value" consists of to parts seperated by a
 142 colon.
 143
 144 The first part is the "mode". The second part is the path to the
 145 interpreter.
 146
 147 At the moment two modes are supported:
 148
 149 "php"-mode: Use this mode for PHP scripts. Specify the PHP-interpreter you
 150   want to use.
 151
 152 "execute"-mode: Must be specified as "execute:!self". Does not take any
 153   interpreter as the script itself is executed. Use this option for
 154   CGI-scripts.
 155
 156 ===================================
 157 (c)2002-2008 by Sebastian Marsching
 158 <sebastian@marsching.com>
 159 Please see LICENSE for
 160 additional information