Introduce mod_privileges: a platform-specific module offering enhanced

<?xml version="1.0"?>

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

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

<!-- $LastChangedRevision: 703441 $ -->

<!--

 Licensed to the Apache Software Foundation (ASF) under one or more

 contributor license agreements.  See the NOTICE file distributed with

 this work for additional information regarding copyright ownership.

 The ASF licenses this file to You under the Apache License, Version 2.0

 (the "License"); you may not use this file except in compliance with

 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software

 distributed under the License is distributed on an "AS IS" BASIS,

 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 See the License for the specific language governing permissions and

 limitations under the License.

-->

<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 <module>perchild</module> MPM.

It also offers other security enhancements.</p>

<p>Unlike <module>perchild</module>, <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>

<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>

<?xml version="1.0" encoding="UTF-8" ?>

<!-- GENERATED FROM XML: DO NOT EDIT -->

<metafile>

  <basename>mod_privileges</basename>

  <path>/mod/</path>

  <relpath>..</relpath>

  <variants>

    <variant>en</variant>

  </variants>

</metafile>

fi

APACHE_MODULE(unixd, unix specific support, , , $unixd_mods_enable)

APACHE_MODULE(privileges, Per-virtualhost Unix UserIDs and enhanced security for Solaris)

APACHE_MODPATH_FINISH