suexec.xml revision 181e56d8b348d301d615ccf5465ae600fee2867b
7d5ac94fda90b837211dadf2585c0fe8c5dc3e5djerenkrantz<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
c330021bf3f45cbf187fa644781e67f7e470a58awrowe<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
62f7716b14b71603a8004434ca3536902bfb8899wrowe<manualpage>
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe Apache users the ability
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe to run <strong>CGI</strong> and <strong>SSI</strong> programs
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe under user IDs different from the user ID of the calling
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe web-server. Normally, when a CGI or SSI program executes, it
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe runs as the same user who is running the web server.</p>
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe <p>Used properly, this feature can reduce
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe considerably the security risks involved with allowing users to
38dc50ae00a1ea57fa41500d74f4e818747e3cefpquerna develop and run private CGI or SSI programs. However, if suEXEC
585895b11fc5072edf78147f9820d97bb020608drjung is improperly configured, it can cause any number of problems
366616a5cc6212cbf7134ccf877f965d668c6b04wrowe and possibly create new holes in your computer's security. If
ecf8d72af432e53e4c0661fb99dfda8061507bfajerenkrantz you aren't familiar with managing setuid root programs and the
f19a8656f9b21bf3e66eb96e25eac2046c2d102bjim security issues they present, we highly recommend that you not
ecf8d72af432e53e4c0661fb99dfda8061507bfajerenkrantz consider using suEXEC.</p>
af4c982a7cf4515f124935f99a329744035fc699slive <p>Before jumping head-first into this document,
f610c7c704235bc327dbe9b62982f5b3f8e30a77wrowe you should be aware of the assumptions made on the part of the
f610c7c704235bc327dbe9b62982f5b3f8e30a77wrowe Apache Group and this document.</p>
d96ee8cda2799e1f2743c1603adeb4833ed0e15fslive <p>First, it is assumed that you are using a UNIX
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe derivate operating system that is capable of
ecf8d72af432e53e4c0661fb99dfda8061507bfajerenkrantz <strong>setuid</strong> and <strong>setgid</strong> operations.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe All command examples are given in this regard. Other platforms,
ecf8d72af432e53e4c0661fb99dfda8061507bfajerenkrantz if they are capable of supporting suEXEC, may differ in their
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe configuration.</p>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <p>Second, it is assumed you are familiar with
d96ee8cda2799e1f2743c1603adeb4833ed0e15fslive some basic concepts of your computer's security and its
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe administration. This involves an understanding of
f610c7c704235bc327dbe9b62982f5b3f8e30a77wrowe <strong>setuid/setgid</strong> operations and the various
dc287e6d736b5998068addfb712936f51818cc0frbowen effects they may have on your system and its level of
dc287e6d736b5998068addfb712936f51818cc0frbowen security.</p>
4b62424416882687387923b3130b96241503cbe0jerenkrantz <p>Third, it is assumed that you are using an
5ca8e11fadb6f7a8d9d0367c1800205c99d4bcd6jerenkrantz <strong>unmodified</strong> version of suEXEC code. All code
62f7716b14b71603a8004434ca3536902bfb8899wrowe for suEXEC has been carefully scrutinized and tested by the
45b0e1c775c1cfed6473c9e5304179ccb9609f53stoddard developers as well as numerous beta testers. Every precaution
dbec4658981e4f9127e8676457c28d42932be7cdtrawick has been taken to ensure a simple yet solidly safe base of
c4beaaf4e697ed012c8c535f849bb13a77620f05sf code. Altering this code can cause unexpected problems and new
c4beaaf4e697ed012c8c535f849bb13a77620f05sf security risks. It is <strong>highly</strong> recommended you
c4beaaf4e697ed012c8c535f849bb13a77620f05sf not alter the suEXEC code unless you are well versed in the
c4beaaf4e697ed012c8c535f849bb13a77620f05sf particulars of security programming and are willing to share
c4beaaf4e697ed012c8c535f849bb13a77620f05sf your work with the Apache Group for consideration.</p>
c4beaaf4e697ed012c8c535f849bb13a77620f05sf <p>Fourth, and last, it has been the decision of
c4beaaf4e697ed012c8c535f849bb13a77620f05sf the Apache Group to <strong>NOT</strong> make suEXEC part of
c4beaaf4e697ed012c8c535f849bb13a77620f05sf the default installation of Apache. To this end, suEXEC
e26be55e30feaa1b3783feaa7060176ae87c9048rjung configuration requires of the administrator careful attention
e26be55e30feaa1b3783feaa7060176ae87c9048rjung to details. After due consideration has been given to the
e26be55e30feaa1b3783feaa7060176ae87c9048rjung various settings for suEXEC, the administrator may install
e26be55e30feaa1b3783feaa7060176ae87c9048rjung suEXEC through normal installation methods. The values for
e26be55e30feaa1b3783feaa7060176ae87c9048rjung these settings need to be carefully determined and specified by
c4beaaf4e697ed012c8c535f849bb13a77620f05sf the administrator to properly maintain system security during
a74ee4396fe11ffc1ca05837a59e497c905eedc3sf the use of suEXEC functionality. It is through this detailed
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe process that the Apache Group hopes to limit suEXEC
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe installation only to those who are careful and determined
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe enough to use it.</p>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe<section id="model"><title>suEXEC Security Model</title>
8e5b782f9a73e0c6de56579b5128b387b1935daasf <p>Before we begin configuring and installing
0db0abcbe4211435c08e0c0e8f5daa278bed3524wsanchez suEXEC, we will first discuss the security model you are about
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe to implement. By doing so, you may better understand what
0db0abcbe4211435c08e0c0e8f5daa278bed3524wsanchez exactly is going on inside suEXEC and what precautions are
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe taken to ensure your system's security.</p>
f6a9b598f78b2e745456bfc4bbc4afd2d1572aa9stas "wrapper" program that is called by the main Apache web server.
bce58f79020e39e5ac5de398fe08b4f8a1e19970pgollucci This wrapper is called when an HTTP request is made for a CGI
62f7716b14b71603a8004434ca3536902bfb8899wrowe or SSI program that the administrator has designated to run as
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz a userid other than that of the main server. When such a
f4cb04eb78da02a38fcdd87489dc7b660107d55fjerenkrantz request is made, Apache provides the suEXEC wrapper with the
53e66a2931d02e84628ba946055cc92e56b43db8wrowe program's name and the user and group IDs under which the
53e66a2931d02e84628ba946055cc92e56b43db8wrowe program is to execute.</p>
53e66a2931d02e84628ba946055cc92e56b43db8wrowe <p>The wrapper then employs the following process
71cda1f2d621dbd9fd3406e35a6f8c412576a15dpgollucci to determine success or failure -- if any one of these
53e66a2931d02e84628ba946055cc92e56b43db8wrowe conditions fail, the program logs the failure and exits with an
1b3f48fd6b1ccb8745f908e40156c5a85ca3c347jerenkrantz error, otherwise it will continue:</p>
99665be7f22b9e3421bd698bd731f82ab0deb827sf <strong>Was the wrapper called with the proper number of
99665be7f22b9e3421bd698bd731f82ab0deb827sf arguments?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe The wrapper will only execute if it is given the proper
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe number of arguments. The proper argument format is known
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe to the Apache web server. If the wrapper is not receiving
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe the proper number of arguments, it is either being
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe hacked, or there is something wrong with the suEXEC
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe portion of your Apache binary.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the user executing this wrapper a valid user of
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe this system?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe This is to ensure that the user executing the wrapper is
979b5dac648b2e3eef4b5a514b3711b58640026bsctemme truly a user of the system.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is this valid user allowed to run the
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe wrapper?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Is this user the user allowed to run this wrapper? Only
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe one user (the Apache user) is allowed to execute this
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Does the target program have an unsafe hierarchical
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe reference?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Does the target program contain a leading '/' or have a
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe '..' backreference? These are not allowed; the target
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe program must reside within the Apache webspace.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Does the target user exist?
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Does the target group exist?
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the target user <em>NOT</em> superuser?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Presently, suEXEC does not allow 'root' to execute
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the target userid <em>ABOVE</em> the minimum ID
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe number?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe The minimum user ID number is specified during
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe configuration. This allows you to set the lowest possible
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe userid that will be allowed to execute CGI/SSI programs.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe This is useful to block out "system" accounts.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the target group <em>NOT</em> the superuser
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe group?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Presently, suEXEC does not allow the 'root' group to
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the target groupid <em>ABOVE</em> the minimum ID
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe number?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe The minimum group ID number is specified during
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe configuration. This allows you to set the lowest possible
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe groupid that will be allowed to execute CGI/SSI programs.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe This is useful to block out "system" groups.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Can the wrapper successfully become the target user
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe and group?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Here is where the program becomes the target user and
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe group via setuid and setgid calls. The group access list
828333c93c6c11a4b46154302515e35cc6982f12sctemme is also initialized with all of the groups of which the
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe user is a member.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Does the directory in which the program resides
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe exist?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe If it doesn't exist, it can't very well contain files.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the directory within the Apache
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe webspace?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe If the request is for a regular portion of the server, is
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe the requested directory within the server's document
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe root? If the request is for a UserDir, is the requested
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe directory within the user's document root?
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the directory <em>NOT</em> writable by anyone
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe else?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe We don't want to open up the directory to others; only
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe the owner user may be able to alter this directories
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe If it doesn't exists, it can't very well be executed.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the target program <em>NOT</em> writable by
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe anyone else?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe We don't want to give anyone other than the owner the
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe ability to change the program.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe setgid?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe We do not want to execute programs that will then change
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Is the target user/group the same as the program's
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Is the user the owner of the file?
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Can we successfully clean the process environment
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe to ensure safe operations?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe suEXEC cleans the process' environment by establishing a
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe safe execution PATH (defined during configuration), as
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe well as only passing through those variables whose names
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe are listed in the safe environment list (also created
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe during configuration).
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <strong>Can we successfully become the target program and
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe execute?</strong>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe Here is where suEXEC ends and the target program begins.
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <p>This is the standard operation of the the
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe suEXEC wrapper's security model. It is somewhat stringent and
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe can impose new limitations and guidelines for CGI/SSI design,
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe but it was developed carefully step-by-step with security in
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <p>For more information as to how this security
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe model can limit your possibilities in regards to server
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe configuration, as well as what security risks can be avoided
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe with a proper suEXEC setup, see the <a
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe href="#jabberwock">"Beware the Jabberwock"</a> section of this
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe document.</p>
62f7716b14b71603a8004434ca3536902bfb8899wrowe<section id="install"><title>Configuring & Installing
28c4fe67d75f8f26504d75b7aa8dc5d868032888wrowe suEXEC</title>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <dd>This option enables the suEXEC feature which is never
820e91baab4f9a45001d668698d2fae3501cb4b0trawick installed or activated by default. At least one
820e91baab4f9a45001d668698d2fae3501cb4b0trawick --with-suexec-xxxxx option has to be provided together with the
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe --enable-suexec option to let APACI accept your request for
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe using the suEXEC feature.</dd>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <dd>The path to the suexec binary must be hard-coded in
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe the server for security reasons. Use this option to override
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <dt><code>--with-suexec-caller=<em>UID</em></code></dt>
ddd44b06b04507cae083c52451e28f54f0bdb5afstoddard <dd>The <a href="mod/mpm_common.html#user">username</a> under which
3a86b95ac291f1af18df0ca2bd6d51c8b35f1241rjung Apache normally runs. This is the only user allowed to
ddd44b06b04507cae083c52451e28f54f0bdb5afstoddard execute this program.</dd>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <dt><code>--with-suexec-userdir=<em>DIR</em></code></dt>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <dd>Define to be the subdirectory under users' home
3a86b95ac291f1af18df0ca2bd6d51c8b35f1241rjung directories where suEXEC access should be allowed. All
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe executables under this directory will be executable by suEXEC
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe as the user so they should be "safe" programs. If you are
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe using a "simple" UserDir directive (ie. one without a "*" in
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe it) this should be set to the same value. suEXEC will not
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe work properly in cases where the UserDir directive points to
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe a location that is not the same as the user's home directory
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe as referenced in the passwd file. Default value is
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe "public_html".<br />
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe If you have virtual hosts with a different UserDir for each,
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe you will need to define them to all reside in one parent
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe directory; then name that parent directory here. <strong>If
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe this is not defined properly, "~userdir" cgi requests will
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <dt><code>--with-suexec-docroot=<em>DIR</em></code></dt>
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe <dd>Define as the DocumentRoot set for Apache. This will be
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe the only hierarchy (aside from UserDirs) that can be used for
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe suEXEC behavior. The default directory is the --datadir value
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe with the suffix "/htdocs", <em>e.g.</em> if you configure
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe with "<code>--datadir=/home/apache</code>" the directory
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe "/home/apache/htdocs" is used as document root for the suEXEC
9e86ff266f053757dd96dab7cf4bc53aaaaa583ewrowe wrapper.</dd>
ec0315cdf832eac2b78e50ad636af84fe4c9118cgstein <dt><code>--with-suexec-uidmin=<em>UID</em></code></dt>
62f7716b14b71603a8004434ca3536902bfb8899wrowe <dd>Define this as the lowest UID allowed to be a target user
62f7716b14b71603a8004434ca3536902bfb8899wrowe for suEXEC. For most systems, 500 or 100 is common. Default
62f7716b14b71603a8004434ca3536902bfb8899wrowe value is 100.</dd>
62f7716b14b71603a8004434ca3536902bfb8899wrowe <dt><code>--with-suexec-gidmin=<em>GID</em></code></dt>
56a6298c5ab82b51c3d6bbda9ec33ca5f1569a7fpquerna <dd>Define this as the lowest GID allowed to be a target
href="http://httpd.apache.org/docs-2.0/suexec.html">Online