<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_privileges.xml.meta">

<name>mod_privileges</name>

<description>Support for Solaris privileges and for running virtual hosts

under different user IDs.</description>

<status>Experimental</status>

<identifier>privileges_module</identifier>

<compatibility>Available in Apache 2.3 and up, on Solaris 10 and

OpenSolaris platforms</compatibility>

<summary>

<p>This module enables different Virtual Hosts to run with different

Unix&trade; <var>User</var> and <var>Group</var> IDs, and with different

<a href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>Solaris Privileges</a>. In particular, it offers a solution to the

problem of privilege separation between different Virtual Hosts, first

promised by the abandoned perchild MPM. It also offers other security

enhancements.</p>

<p>Unlike perchild, <module>mod_privileges</module>

is not itself an MPM. It works <em>within</em> a processing model to

set privileges and User/Group <em>per request</em> in a running process.

It is therefore not compatible with a threaded MPM, and will refuse

to run under one.</p>

<p><module>mod_privileges</module> raises security issues similar to

those of <a href="/suexec.html">suexec</a>. But unlike suexec,

it applies not only to CGI programs but to the entire request processing

cycle, including in-process applications and subprocesses.

It is ideally suited to running PHP applications under <strong>mod_php</strong>,

which is also incompatible with threaded MPMs. It is also well-suited

to other in-process scripting applications such as <strong>mod_perl</strong>,

<strong>mod_python</strong>, and <strong>mod_ruby</strong>, and to

applications implemented in C as apache modules where privilege

separation is an issue.</p>

</summary>

<section id="security"><title>Security Considerations</title>

<p><module>mod_privileges</module> introduces new security concerns

in situations where <strong>untrusted code</strong> may be run

<strong>within the webserver process</strong>. This applies to

untrusted modules, and scripts running under modules such as

mod_php or mod_perl. Scripts running externally (e.g. as CGI

or in an appserver behind mod_proxy or mod_jk) are NOT affected.</p>

<p>The basic security concerns with mod_privileges are:</p>

<ul><li>Running as a system user introduces the same security issues

as mod_suexec, and near-equivalents such as cgiwrap and suphp.</li>

<li>A privileges-aware malicious user extension (module or script)

could escalate its privileges to anything available to the

httpd process in any virtual host. This introduces new risks

if (and only if) mod_privileges is compiled with the

<var>BIG_SECURITY_HOLE</var> option.</li>

<li>A privileges-aware malicious user extension (module or script)

could escalate privileges to set its user ID to another system

user (and/or group).</li>

</ul>

<p>The <directive>PrivilegesMode</directive> directive allows you to

select either <var>FAST</var> or <var>SECURE</var> mode. You can

mix modes, using <var>FAST</var> mode for trusted users and

fully-audited code paths, while imposing SECURE mode where an

untrusted user has scope to introduce code.</p>

<p>Before describing the modes, we should also introduce the target

use cases: Benign vs Hostile. In a benign situation, you want to

separate users for their convenience, and protect them and the server

against the risks posed by honest mistakes, but you trust your users

are not deliberately subverting system security. In a hostile

situation - e.g. commercial hosting - you may have users deliberately

attacking the system or each other.</p>

<dl>

<dt>FAST mode</dt>

<dd>In <var>FAST</var> mode, requests are run in-process with the

selected uid/gid and privileges, so the overhead is negligible.

This is suitable for benign situations, but is not secure against an

attacker escalating privileges with an in-process module or script.</dd>

<dt>SECURE mode</dt>

<dd>A request in <var>SECURE</var> mode forks a subprocess, which

then drops privileges. This is a very similar case to running CGI

with suexec, but for the entire request cycle, and with the benefit

of fine-grained control of privileges.</dd>

</dl>

<p>You can select different <directive>PrivilegesMode</directive>s for

each virtual host, and even in a directory context within a virtual

host. <var>FAST</var> mode is appropriate where the user(s) are

trusted and/or have no privilege to load in-process code.

<var>SECURE</var> mode is appropriate to cases where untrusted code

might be run in-process. However, even in <var>SECURE</var> mode,

there is no protection against a malicious user who is able to

introduce privileges-aware code running <em>before the start of the

request-processing cycle.</em></p>

</section>

<directivesynopsis>

<name>PrivilegesMode</name>

<description>Trade off processing speed and efficiency vs security against

malicious privileges-aware code.</description>

<syntax>PrivilegesMode FAST|SECURE|SELECTIVE</syntax>

<contextlist>

<context>server config</context>

<context>virtual host</context>

<context>directory</context>

</contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>

<usage><p>This directive trades off performance vs security against

malicious, privileges-aware code. In <var>SECURE</var> mode, each request

runs in a secure subprocess, incurring a substantial performance penalty.

In <var>FAST</var> mode, the server is not protected against escalation

of privileges as discussed above.</p>

<p>This directive differs slightly between a <code>&lt;Directory&gt;</code>

context (including equivalents such as Location/Files/If) and a

top-level or <code>&lt;VirtualHost&gt;</code>.</p>

<p>At top-level, it sets a default that will be inherited by virtualhosts.

In a virtual host, FAST or SECURE mode acts on the entire

HTTP request, and any settings in a <code>&lt;Directory&gt;</code>

context will be <strong>ignored</strong>. A third pseudo-mode

SELECTIVE defers the choice of FAST vs SECURE to directives in a

<code>&lt;Directory&gt;</code> context.</p>

<p>In a <code>&lt;Directory&gt;</code> context, it is applicable only

where SELECTIVE mode was set for the VirtualHost. Only

FAST or SECURE can be set in this context (SELECTIVE would be

meaningless).</p>

<note type="warning"><title>Warning</title>

Where SELECTIVE mode is selected for a virtual host, the activation

of privileges must be deferred until <em>after</em> the mapping

phase of request processing has determined what

<code>&lt;Directory&gt;</code> context applies to the request.

This might give an attacker opportunities to introduce

code through a <directive module="mod_rewrite">RewriteMap</directive>

running at top-level or <code>&lt;VirtualHost&gt;</code> context

<em>before</em> privileges have been dropped and userid/gid set.

</note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>VHostUser</name>

<description>Sets the User ID under which a virtual host runs.</description>

<syntax>VHostUser <var>unix-userid</var></syntax>

<default>Inherits the userid specified in

<directive module="mod_unixd">User</directive></default>

<contextlist><context>virtual host</context></contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>

<usage>

<p>The <directive>VHostUser</directive> directive sets the Unix userid

under which the server will process requests to a virtualhost.

The userid is set before the request is processed and reset afterwards

using <a

href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>Solaris Privileges</a>. Since the setting applies to the

<em>process</em>, this is not compatible with threaded MPMs.</p>

<p><var>Unix-userid</var> is one of:</p>

<dl>

<dt>A username</dt>

<dd>Refers to the given user by name.</dd>

<dt><code>#</code> followed by a user number.</dt>

<dd>Refers to a user by its number.</dd>

</dl>

<note type="warning"><title>Security</title>

<p>This directive cannot be used to run apache as root!

Nevertheless, it opens potential security issues similar to

those discussed in the <a href="/suexec.html">suexec</a>

documentation.</p></note>

</usage>

<seealso><directive module="mod_unixd">User</directive></seealso>

<seealso><directive module="mod_suexec">SuexecUserGroup</directive></seealso>

</directivesynopsis>

<directivesynopsis>

<name>VHostGroup</name>

<description>Sets the Group ID under which a virtual host runs.</description>

<syntax>VHostGroup <var>unix-groupid</var></syntax>

<default>Inherits the group id specified in

<directive module="mod_unixd">Group</directive></default>

<contextlist><context>virtual host</context></contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>

<usage>

<p>The <directive>VHostGroup</directive> directive sets the Unix group

under which the server will process requests to a virtualhost.

The group is set before the request is processed and reset afterwards

using <a

href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>Solaris Privileges</a>. Since the setting applies to the

<em>process</em>, this is not compatible with threaded MPMs.</p>

<p><var>Unix-group</var> is one of:</p>

<dl>

<dt>A group name</dt>

<dd>Refers to the given group by name.</dd>

<dt><code>#</code> followed by a group number.</dt>

<dd>Refers to a group by its number.</dd>

</dl>

<note type="warning"><title>Security</title>

<p>This directive cannot be used to run apache as root!

Nevertheless, it opens potential security issues similar to

those discussed in the <a href="/suexec.html">suexec</a>

documentation.</p></note>

</usage>

<seealso><directive module="mod_unixd">Group</directive></seealso>

<seealso><directive module="mod_suexec">SuexecUserGroup</directive></seealso>

</directivesynopsis>

<directivesynopsis>

<name>VHostSecure</name>

<description>Determines whether the server runs with enhanced security

for the virtualhost.</description>

<syntax>VHostSecure On|Off</syntax>

<default>VHostSecure On</default>

<contextlist><context>virtual host</context></contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>

<usage>

<p>Determines whether the virtual host processes requests with

security enhanced by removal of <a

href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>Privileges</a> that are rarely needed in a webserver, but which are

available by default to a normal Unix user and may therefore

be required by modules and applications. It is recommended that

you retain the default (On) unless it prevents an application running.

Since the setting applies to the <em>process</em>, this is not

compatible with threaded MPMs.</p>

<note><title>Note</title>

<p>If <directive>VHostSecure</directive> prevents an application

running, this may be a warning sign that the application should be

reviewed for security.</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>VHostCGIMode</name>

<description>Determines whether the virtualhost can run

subprocesses, and the privileges available to subprocesses.</description>

<syntax>VHostCGIMode On|Off|Secure</syntax>

<default>VHostCGIMode On</default>

<contextlist><context>virtual host</context></contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>

<usage>

<p>Determines whether the virtual host is allowed to run fork and exec,

the <a

href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>privileges</a> required to run subprocesses. If this is set to

<var>Off</var> the virtualhost is denied the privileges and will not

be able to run traditional CGI programs or scripts under the traditional

<module>mod_cgi</module>, nor similar external programs such as those

created by <module>mod_ext_filter</module> or

<directive module="mod_rewrite">RewriteMap</directive> <var>prog</var>.

Note that it does not prevent CGI programs running under alternative

process and security models such as <a href="http://fastcgi.coremail.cn"

>mod_fcgid</a>, which is a recommended solution in Solaris.</p>

<p>If set to <var>On</var> or <var>Secure</var>, the virtual host

is permitted to run external programs and scripts as above.

Setting <directive>VHostCGIMode</directive> <var>Secure</var> has

the effect of denying privileges to the subprocesses, as described

for <directive>VHostSecure</directive>.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>DTracePrivileges</name>

<description>Determines whether the privileges required by dtrace are enabled.</description>

<syntax>DTracePrivileges On|Off</syntax>

<default>DTracePrivileges Off</default>

<contextlist><context>server config</context></contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM).</compatibility>

<usage>

<p>This server-wide directive determines whether Apache will run with

the <a

href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>privileges</a> required to run

<a href="http://www.sun.com/bigadmin/content/dtrace/">dtrace</a>.

Note that <var>DTracePrivileges On</var> will not in itself

activate DTrace, but <var>DTracePrivileges Off</var> will prevent

it working.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>VHostPrivs</name>

<description>Assign arbitrary privileges to a virtual host.</description>

<syntax>VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</syntax>

<default>None</default>

<contextlist><context>virtual host</context></contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM)

and when <module>mod_privileges</module> is compiled with the

<var>BIG_SECURITY_HOLE</var> compile-time option.</compatibility>

<usage>

<p><directive>VHostPrivs</directive> can be used to assign arbitrary <a

href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>privileges</a> to a virtual host. Each <var>privilege-name</var>

is the name of a Solaris privilege, such as <var>file_setid</var>

or <var>sys_nfs</var>.</p>

<p>A <var>privilege-name</var> may optionally be prefixed by

+ or -, which will respectively allow or deny a privilege.

If used with neither + nor -, all privileges otherwise assigned

to the virtualhost will be denied. You can use this to override

any of the default sets and construct your own privilege set.</p>

<note type="warning"><title>Security</title>

<p>This directive can open huge security holes in apache, up to

and including running requests with root-level powers. Do not

use it unless you fully understand what you are doing!</p></note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>VHostCGIPrivs</name>

<description>Assign arbitrary privileges to subprocesses created

by a virtual host.</description>

<syntax>VHostPrivs [+-]?<var>privilege-name</var> [[+-]?privilege-name] ...</syntax>

<default>None</default>

<contextlist><context>virtual host</context></contextlist>

<compatibility>Available on Solaris 10 and OpenSolaris with

non-threaded MPMs (<module>prefork</module> or custom MPM)

and when <module>mod_privileges</module> is compiled with the

<var>BIG_SECURITY_HOLE</var> compile-time option.</compatibility>

<usage>

<p><directive>VHostCGIPrivs</directive> can be used to assign arbitrary <a

href="http://www.sun.com/bigadmin/features/articles/least_privilege.jsp"

>privileges</a> to subprocesses created by a virtual host, as discussed

under <directive>VHostCGIMode</directive>. Each <var>privilege-name</var>

is the name of a Solaris privilege, such as <var>file_setid</var>

or <var>sys_nfs</var>.</p>

<p>A <var>privilege-name</var> may optionally be prefixed by

+ or -, which will respectively allow or deny a privilege.

If used with neither + nor -, all privileges otherwise assigned

to the virtualhost will be denied. You can use this to override

any of the default sets and construct your own privilege set.</p>

<note type="warning"><title>Security</title>

<p>This directive can open huge security holes in apache subprocesses,

up to and including running them with root-level powers. Do not

use it unless you fully understand what you are doing!</p></note>

</usage>

</directivesynopsis>

</modulesynopsis>