2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_privileges.xml.meta">
25 <name>mod_privileges</name>
26 <description>Support for Solaris privileges and for running virtual hosts
27 under different user IDs.</description>
28 <status>Experimental</status>
29 <sourcefile>mod_privileges.c</sourcefile>
30 <identifier>privileges_module</identifier>
31 <compatibility>Available in Apache 2.3 and up, on Solaris 10 and
32 OpenSolaris platforms</compatibility>
35 <p>This module enables different Virtual Hosts to run with different
36 Unix <var>User</var> and <var>Group</var> IDs, and with different
37 <a href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
38 >Solaris Privileges</a>. In particular, it offers a solution to the
39 problem of privilege separation between different Virtual Hosts, first
40 promised by the abandoned perchild MPM. It also offers other security
43 <p>Unlike perchild, <module>mod_privileges</module>
44 is not itself an MPM. It works <em>within</em> a processing model to
45 set privileges and User/Group <em>per request</em> in a running process.
46 It is therefore not compatible with a threaded MPM, and will refuse
49 <p><module>mod_privileges</module> raises security issues similar to
50 those of <a href="../suexec.html">suexec</a>. But unlike suexec,
51 it applies not only to CGI programs but to the entire request processing
52 cycle, including in-process applications and subprocesses.
53 It is ideally suited to running PHP applications under <strong>mod_php</strong>,
54 which is also incompatible with threaded MPMs. It is also well-suited
55 to other in-process scripting applications such as <strong>mod_perl</strong>,
56 <strong>mod_python</strong>, and <strong>mod_ruby</strong>, and to
57 applications implemented in C as apache modules where privilege
58 separation is an issue.</p>
62 <section id="security"><title>Security Considerations</title>
64 <p><module>mod_privileges</module> introduces new security concerns
65 in situations where <strong>untrusted code</strong> may be run
66 <strong>within the webserver process</strong>. This applies to
67 untrusted modules, and scripts running under modules such as
68 mod_php or mod_perl. Scripts running externally (e.g. as CGI
69 or in an appserver behind mod_proxy or mod_jk) are NOT affected.</p>
71 <p>The basic security concerns with mod_privileges are:</p>
72 <ul><li>Running as a system user introduces the same security issues
73 as mod_suexec, and near-equivalents such as cgiwrap and suphp.</li>
74 <li>A privileges-aware malicious user extension (module or script)
75 could escalate its privileges to anything available to the
76 httpd process in any virtual host. This introduces new risks
77 if (and only if) mod_privileges is compiled with the
78 <var>BIG_SECURITY_HOLE</var> option.</li>
79 <li>A privileges-aware malicious user extension (module or script)
80 could escalate privileges to set its user ID to another system
81 user (and/or group).</li>
84 <p>The <directive>PrivilegesMode</directive> directive allows you to
85 select either <var>FAST</var> or <var>SECURE</var> mode. You can
86 mix modes, using <var>FAST</var> mode for trusted users and
87 fully-audited code paths, while imposing SECURE mode where an
88 untrusted user has scope to introduce code.</p>
89 <p>Before describing the modes, we should also introduce the target
90 use cases: Benign vs Hostile. In a benign situation, you want to
91 separate users for their convenience, and protect them and the server
92 against the risks posed by honest mistakes, but you trust your users
93 are not deliberately subverting system security. In a hostile
94 situation - e.g. commercial hosting - you may have users deliberately
95 attacking the system or each other.</p>
98 <dd>In <var>FAST</var> mode, requests are run in-process with the
99 selected uid/gid and privileges, so the overhead is negligible.
100 This is suitable for benign situations, but is not secure against an
101 attacker escalating privileges with an in-process module or script.</dd>
103 <dd>A request in <var>SECURE</var> mode forks a subprocess, which
104 then drops privileges. This is a very similar case to running CGI
105 with suexec, but for the entire request cycle, and with the benefit
106 of fine-grained control of privileges.</dd>
108 <p>You can select different <directive>PrivilegesMode</directive>s for
109 each virtual host, and even in a directory context within a virtual
110 host. <var>FAST</var> mode is appropriate where the user(s) are
111 trusted and/or have no privilege to load in-process code.
112 <var>SECURE</var> mode is appropriate to cases where untrusted code
113 might be run in-process. However, even in <var>SECURE</var> mode,
114 there is no protection against a malicious user who is able to
115 introduce privileges-aware code running <em>before the start of the
116 request-processing cycle.</em></p>
120 <name>PrivilegesMode</name>
121 <description>Trade off processing speed and efficiency vs security against
122 malicious privileges-aware code.</description>
123 <syntax>PrivilegesMode FAST|SECURE|SELECTIVE</syntax>
124 <default>PrivilegesMode FAST</default>
126 <context>server config</context>
127 <context>virtual host</context>
128 <context>directory</context>
130 <compatibility>Available on Solaris 10 and OpenSolaris with
131 non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>
132 <usage><p>This directive trades off performance vs security against
133 malicious, privileges-aware code. In <var>SECURE</var> mode, each request
134 runs in a secure subprocess, incurring a substantial performance penalty.
135 In <var>FAST</var> mode, the server is not protected against escalation
136 of privileges as discussed above.</p>
137 <p>This directive differs slightly between a <code><Directory></code>
138 context (including equivalents such as Location/Files/If) and a
139 top-level or <code><VirtualHost></code>.</p>
140 <p>At top-level, it sets a default that will be inherited by virtualhosts.
141 In a virtual host, FAST or SECURE mode acts on the entire
142 HTTP request, and any settings in a <code><Directory></code>
143 context will be <strong>ignored</strong>. A third pseudo-mode
144 SELECTIVE defers the choice of FAST vs SECURE to directives in a
145 <code><Directory></code> context.</p>
146 <p>In a <code><Directory></code> context, it is applicable only
147 where SELECTIVE mode was set for the VirtualHost. Only
148 FAST or SECURE can be set in this context (SELECTIVE would be
150 <note type="warning"><title>Warning</title>
151 Where SELECTIVE mode is selected for a virtual host, the activation
152 of privileges must be deferred until <em>after</em> the mapping
153 phase of request processing has determined what
154 <code><Directory></code> context applies to the request.
155 This might give an attacker opportunities to introduce
156 code through a <directive module="mod_rewrite">RewriteMap</directive>
157 running at top-level or <code><VirtualHost></code> context
158 <em>before</em> privileges have been dropped and userid/gid set.
164 <name>VHostUser</name>
165 <description>Sets the User ID under which a virtual host runs.</description>
166 <syntax>VHostUser <var>unix-userid</var></syntax>
167 <default>Inherits the userid specified in
168 <directive module="mod_unixd">User</directive></default>
169 <contextlist><context>virtual host</context></contextlist>
170 <compatibility>Available on Solaris 10 and OpenSolaris with
171 non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>
174 <p>The <directive>VHostUser</directive> directive sets the Unix userid
175 under which the server will process requests to a virtualhost.
176 The userid is set before the request is processed and reset afterwards
178 href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
179 >Solaris Privileges</a>. Since the setting applies to the
180 <em>process</em>, this is not compatible with threaded MPMs.</p>
181 <p><var>Unix-userid</var> is one of:</p>
184 <dd>Refers to the given user by name.</dd>
186 <dt><code>#</code> followed by a user number.</dt>
187 <dd>Refers to a user by its number.</dd>
190 <note type="warning"><title>Security</title>
191 <p>This directive cannot be used to run apache as root!
192 Nevertheless, it opens potential security issues similar to
193 those discussed in the <a href="../suexec.html">suexec</a>
194 documentation.</p></note>
196 <seealso><directive module="mod_unixd">User</directive></seealso>
197 <seealso><directive module="mod_suexec">SuexecUserGroup</directive></seealso>
201 <name>VHostGroup</name>
202 <description>Sets the Group ID under which a virtual host runs.</description>
203 <syntax>VHostGroup <var>unix-groupid</var></syntax>
204 <default>Inherits the group id specified in
205 <directive module="mod_unixd">Group</directive></default>
206 <contextlist><context>virtual host</context></contextlist>
207 <compatibility>Available on Solaris 10 and OpenSolaris with
208 non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>
211 <p>The <directive>VHostGroup</directive> directive sets the Unix group
212 under which the server will process requests to a virtualhost.
213 The group is set before the request is processed and reset afterwards
215 href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
216 >Solaris Privileges</a>. Since the setting applies to the
217 <em>process</em>, this is not compatible with threaded MPMs.</p>
218 <p><var>Unix-group</var> is one of:</p>
220 <dt>A group name</dt>
221 <dd>Refers to the given group by name.</dd>
223 <dt><code>#</code> followed by a group number.</dt>
224 <dd>Refers to a group by its number.</dd>
227 <note type="warning"><title>Security</title>
228 <p>This directive cannot be used to run apache as root!
229 Nevertheless, it opens potential security issues similar to
230 those discussed in the <a href="../suexec.html">suexec</a>
231 documentation.</p></note>
233 <seealso><directive module="mod_unixd">Group</directive></seealso>
234 <seealso><directive module="mod_suexec">SuexecUserGroup</directive></seealso>
238 <name>VHostSecure</name>
239 <description>Determines whether the server runs with enhanced security
240 for the virtualhost.</description>
241 <syntax>VHostSecure On|Off</syntax>
242 <default>VHostSecure On</default>
243 <contextlist><context>virtual host</context></contextlist>
244 <compatibility>Available on Solaris 10 and OpenSolaris with
245 non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>
248 <p>Determines whether the virtual host processes requests with
249 security enhanced by removal of <a
250 href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
251 >Privileges</a> that are rarely needed in a webserver, but which are
252 available by default to a normal Unix user and may therefore
253 be required by modules and applications. It is recommended that
254 you retain the default (On) unless it prevents an application running.
255 Since the setting applies to the <em>process</em>, this is not
256 compatible with threaded MPMs.</p>
257 <note><title>Note</title>
258 <p>If <directive>VHostSecure</directive> prevents an application
259 running, this may be a warning sign that the application should be
260 reviewed for security.</p></note>
265 <name>VHostCGIMode</name>
266 <description>Determines whether the virtualhost can run
267 subprocesses, and the privileges available to subprocesses.</description>
268 <syntax>VHostCGIMode On|Off|Secure</syntax>
269 <default>VHostCGIMode On</default>
270 <contextlist><context>virtual host</context></contextlist>
271 <compatibility>Available on Solaris 10 and OpenSolaris with
272 non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>
275 <p>Determines whether the virtual host is allowed to run fork and exec,
277 href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
278 >privileges</a> required to run subprocesses. If this is set to
279 <var>Off</var> the virtualhost is denied the privileges and will not
280 be able to run traditional CGI programs or scripts under the traditional
281 <module>mod_cgi</module>, nor similar external programs such as those
282 created by <module>mod_ext_filter</module> or
283 <directive module="mod_rewrite">RewriteMap</directive> <var>prog</var>.
284 Note that it does not prevent CGI programs running under alternative
285 process and security models such as <a href="http://fastcgi.coremail.cn"
286 >mod_fcgid</a>, which is a recommended solution in Solaris.</p>
287 <p>If set to <var>On</var> or <var>Secure</var>, the virtual host
288 is permitted to run external programs and scripts as above.
289 Setting <directive>VHostCGIMode</directive> <var>Secure</var> has
290 the effect of denying privileges to the subprocesses, as described
291 for <directive>VHostSecure</directive>.</p>
296 <name>DTracePrivileges</name>
297 <description>Determines whether the privileges required by dtrace are enabled.</description>
298 <syntax>DTracePrivileges On|Off</syntax>
299 <default>DTracePrivileges Off</default>
300 <contextlist><context>server config</context></contextlist>
301 <compatibility>Available on Solaris 10 and OpenSolaris with
302 non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>
305 <p>This server-wide directive determines whether Apache will run with
307 href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
308 >privileges</a> required to run
309 <a href="http://sosc-dr.sun.com/bigadmin/content/dtrace/">dtrace</a>.
310 Note that <var>DTracePrivileges On</var> will not in itself
311 activate DTrace, but <var>DTracePrivileges Off</var> will prevent
317 <name>VHostPrivs</name>
318 <description>Assign arbitrary privileges to a virtual host.</description>
319 <syntax>VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</syntax>
320 <default>None</default>
321 <contextlist><context>virtual host</context></contextlist>
322 <compatibility>Available on Solaris 10 and OpenSolaris with
323 non-threaded MPMs (<module>prefork</module> or custom MPM)
324 and when <module>mod_privileges</module> is compiled with the
325 <var>BIG_SECURITY_HOLE</var> compile-time option.</compatibility>
328 <p><directive>VHostPrivs</directive> can be used to assign arbitrary <a
329 href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
330 >privileges</a> to a virtual host. Each <var>privilege-name</var>
331 is the name of a Solaris privilege, such as <var>file_setid</var>
332 or <var>sys_nfs</var>.</p>
334 <p>A <var>privilege-name</var> may optionally be prefixed by
335 + or -, which will respectively allow or deny a privilege.
336 If used with neither + nor -, all privileges otherwise assigned
337 to the virtualhost will be denied. You can use this to override
338 any of the default sets and construct your own privilege set.</p>
340 <note type="warning"><title>Security</title>
341 <p>This directive can open huge security holes in apache, up to
342 and including running requests with root-level powers. Do not
343 use it unless you fully understand what you are doing!</p></note>
348 <name>VHostCGIPrivs</name>
349 <description>Assign arbitrary privileges to subprocesses created
350 by a virtual host.</description>
351 <syntax>VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</syntax>
352 <default>None</default>
353 <contextlist><context>virtual host</context></contextlist>
354 <compatibility>Available on Solaris 10 and OpenSolaris with
355 non-threaded MPMs (<module>prefork</module> or custom MPM)
356 and when <module>mod_privileges</module> is compiled with the
357 <var>BIG_SECURITY_HOLE</var> compile-time option.</compatibility>
360 <p><directive>VHostCGIPrivs</directive> can be used to assign arbitrary <a
361 href="http://sosc-dr.sun.com/bigadmin/features/articles/least_privilege.jsp"
362 >privileges</a> to subprocesses created by a virtual host, as discussed
363 under <directive>VHostCGIMode</directive>. Each <var>privilege-name</var>
364 is the name of a Solaris privilege, such as <var>file_setid</var>
365 or <var>sys_nfs</var>.</p>
367 <p>A <var>privilege-name</var> may optionally be prefixed by
368 + or -, which will respectively allow or deny a privilege.
369 If used with neither + nor -, all privileges otherwise assigned
370 to the virtualhost will be denied. You can use this to override
371 any of the default sets and construct your own privilege set.</p>
373 <note type="warning"><title>Security</title>
374 <p>This directive can open huge security holes in apache subprocesses,
375 up to and including running them with root-level powers. Do not
376 use it unless you fully understand what you are doing!</p></note>