Fix permissions to make git-buildpackage shut up
[hcoop/zz_old/debian/suphp.git] / 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