suexec.html.en revision db81e057b060e365d840d9a1d35a5797192efa81
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major BGCOLOR="#FFFFFF"
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major TEXT="#000000"
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major LINK="#0000FF"
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major VLINK="#000080"
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major ALINK="#FF0000"
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major<!--#include virtual="header.html" -->
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major <LI><A HREF="#model">suEXEC Security Model.</A></LI>
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI>
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings &
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkThe <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkApache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkprograms under user IDs different from the user ID of the calling web-server.
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkNormally, when a CGI or SSI program executes, it runs as the same user who is
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkrunning the web server.
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkUsed properly, this feature can reduce considerably the security risks involved
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkwith allowing users to develop and run private CGI or SSI programs. However,
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkif suEXEC is improperly configured, it can cause any number of problems and
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkpossibly create new holes in your computer's security. If you aren't familiar
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkwith managing setuid root programs and the security issues they present, we
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenkhighly recommend that you not consider using suEXEC.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkBefore jumping head-first into this document, you should be aware of the
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craigassumptions made on the part of the Apache Group and this document.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkFirst, it is assumed that you are using a UNIX derivate operating system that
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkis capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkAll command examples are given in this regard. Other platforms, if they are
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkcapable of supporting suEXEC, may differ in their configuration.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkSecond, it is assumed you are familiar with some basic concepts of your
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkcomputer's security and its administration. This involves an understanding
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkof <STRONG>setuid/setgid</STRONG> operations and the various effects they
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkmay have on your system and its level of security.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkThird, it is assumed that you are using an <STRONG>unmodified</STRONG>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkversion of suEXEC code. All code for suEXEC has been carefully scrutinized and
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenktested by the developers as well as numerous beta testers. Every precaution has
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkbeen taken to ensure a simple yet solidly safe base of code. Altering this
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkcode can cause unexpected problems and new security risks. It is
01f354c3c43b0b35898db65b63b85bf806ba19b3Mark Craig<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkare well versed in the particulars of security programming and are willing to
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkshare your work with the Apache Group for consideration.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkFourth, and last, it has been the decision of the Apache Group to
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkTo this end, suEXEC configuration is a manual process requiring of the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkadministrator careful attention to details. It is through this process
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkthat the Apache Group hopes to limit suEXEC installation only to those
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkwho are determined to use it.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkStill with us? Yes? Good. Let's move on!
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<H3><A NAME="model">suEXEC Security Model</A></H3>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkBefore we begin configuring and installing suEXEC, we will first discuss
65db5ed2058ee6670116f97ba2c17331eee35f78Peter Majorthe security model you are about to implement. By doing so, you may
65db5ed2058ee6670116f97ba2c17331eee35f78Peter Majorbetter understand what exactly is going on inside suEXEC and what precautions
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkare taken to ensure your system's security.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG>suEXEC</STRONG> is based on a setuid "wrapper" program that is
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkcalled by the main Apache web server. This wrapper is called when an HTTP
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Majorrequest is made for a CGI or SSI program that the administrator has designated
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Majorto run as a userid other than that of the main server. When such a request
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenkis made, Apache provides the suEXEC wrapper with the program's name and the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkuser and group IDs under which the program is to execute.
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill CunningtonThe wrapper then employs the following process to determine success or
eb4311433a3029d6399209e2eaa547999daa0a61Peter Majorfailure -- if any one of these conditions fail, the program logs the failure
66f6c6680ec1673ff6f1094a9e2b74967dd6bfb7jeff.schenkand exits with an error, otherwise it will continue:
323199dbf3b71ff59d304d53db996b6d27ab89a3Phill Cunnington <LI><STRONG>Was the wrapper called with the proper number of arguments?</STRONG>
79548739f9435fe773cfba8e50d906f8eb64bae2Jake Feasel The wrapper will only execute if it is given the proper number of arguments.
c8e5acbef32edea57daf744a4cc55f42abf90278Peter Major The proper argument format is known to the Apache web server. If the wrapper
0701f265e9184ff9b1231d191d007322fc133bdbjeff.schenk is not receiving the proper number of arguments, it is either being hacked, or
573a609d9f2a893765e5df5542ea8f1ce6125c54Jason Lemay there is something wrong with the suEXEC portion of your Apache binary.
9b064c65a05249dcf24ef43f0c485dae99f3711ePhill Cunnington </BLOCKQUOTE>
36919004a94baa0e5cd71c3c8dd55f9ce8c9788bPhill Cunnington <LI><STRONG>Is the user executing this wrapper a valid user of this system?</STRONG>
3172211e5a3f25bf006e07d2fe8bd32ac036b9caPeter Major <BLOCKQUOTE>
0b03f6a75c899702be840c5d00531d234bcb0810Dirk Hogan This is to ensure that the user executing the wrapper is truly a user of the system.
3172211e5a3f25bf006e07d2fe8bd32ac036b9caPeter Major </BLOCKQUOTE>
9d406c6b25ce9f6bf266b077443e723b95962914Dirk Hogan <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper Is this user the user allowed to run this wrapper? Only one user (the Apache
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper user) is allowed to execute this program.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Does the target program have an unsafe hierarchical reference?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper Does the target program contain a leading '/' or have a '..' backreference? These
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper are not allowed; the target program must reside within the Apache webspace.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
9b064c65a05249dcf24ef43f0c485dae99f3711ePhill Cunnington <LI><STRONG>Is the target user name valid?</STRONG>
c44bbf5d2025d672efe11a37ea6e9c867e78b691Neil Madden Does the target user exist?
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Is the target group name valid?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper Does the target group exist?
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper Presently, suEXEC does not allow 'root' to execute CGI/SSI programs.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID number?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper The minimum user ID number is specified during configuration. This allows you
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper to set the lowest possible userid that will be allowed to execute CGI/SSI programs.
971de91bce73bb05574a64c4304daf9f60e2b5b8Neil Madden This is useful to block out "system" accounts.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper Presently, suEXEC does not allow the 'root' group to execute CGI/SSI programs.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID number?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper The minimum group ID number is specified during configuration. This allows you
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper to set the lowest possible groupid that will be allowed to execute CGI/SSI programs.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper This is useful to block out "system" groups.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Can the wrapper successfully become the target user and group?</STRONG>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper Here is where the program becomes the target user and group via setuid and setgid
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper calls. The group access list is also initialized with all of the groups of which
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper the user is a member.
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper </BLOCKQUOTE>
fbb37289e2100511fbb9c5a5667903af04c3e434Mark de Reeper <LI><STRONG>Does the directory in which the program resides exist?</STRONG>
33908fb93167e643fbb21b47d87c5b632df0dc59Phill Cunnington If it doesn't exist, it can't very well contain files.
40b03a530836fb4b75141456a5ad991d7130d91djeff.schenk </BLOCKQUOTE>
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig <LI><STRONG>Is the directory within the Apache webspace?</STRONG>
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig <BLOCKQUOTE>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden If the request is for a regular portion of the server, is the requested directory
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden within the server's document root? If the request is for a UserDir, is the requested
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden directory within the user's document root?
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden </BLOCKQUOTE>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk We don't want to open up the directory to others; only the owner user may be able
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk to alter this directories contents.
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk </BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <LI><STRONG>Does the target program exist?</STRONG>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk If it doesn't exists, it can't very well be executed.
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk </BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone else?</STRONG>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk We don't want to give anyone other than the owner the ability to change the program.
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk </BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk We do not want to execute programs that will then change our UID/GID again.
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk </BLOCKQUOTE>
f136a2a859728f0e788f7cd005d6144b6b0139a2Peter Major <LI><STRONG>Is the target user/group the same as the program's user/group?</STRONG>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk Is the user the owner of the file?
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk </BLOCKQUOTE>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <LI><STRONG>Can we successfully clean the process environment to ensure safe operations?</STRONG>
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk <BLOCKQUOTE>
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major suEXEC cleans the process' environment by establishing a safe execution PATH (defined
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major during configuration), as well as only passing through those variables whose names
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major are listed in the safe environment list (also created during configuration).
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major </BLOCKQUOTE>
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major <LI><STRONG>Can we successfully become the target program and execute?</STRONG>
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major <BLOCKQUOTE>
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major Here is where suEXEC ends and the target program begins.
725ea03dc2bbc656d209dc7b143c795be153cd10Peter Major </BLOCKQUOTE>
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill CunningtonThis is the standard operation of the the suEXEC wrapper's security model.
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill CunningtonIt is somewhat stringent and can impose new limitations and guidelines for
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill CunningtonCGI/SSI design, but it was developed carefully step-by-step with security
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill CunningtonFor more information as to how this security model can limit your possibilities
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunningtonin regards to server configuration, as well as what security risks can be avoided
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunningtonwith a proper suEXEC setup, see the <A HREF="#beware">"Beware the Jabberwock"</A>
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunningtonsection of this document.
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunnington<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
16d0ef277ee8c0b63a22677bbcf87a53bdd62e65Neil Madden<H3><A NAME="install">Configuring & Installing suEXEC</A></H3>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil MaddenHere's where we begin the fun. The configuration and installation of suEXEC is
16d0ef277ee8c0b63a22677bbcf87a53bdd62e65Neil Maddena four step process: edit the suEXEC header file, compile suEXEC, place the
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil MaddensuEXEC binary in its proper location, and configure Apache for use with suEXEC.
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden<STRONG>EDITING THE SUEXEC HEADER FILE</STRONG><BR>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden- From the top-level of the Apache source tree, type:
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil MaddenEdit the <code>suexec.h</code> file and change the following macros to
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Maddenmatch your local Apache installation.
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunnington * HTTPD_USER -- Define as the username under which Apache normally
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunnington * runs. This is the only user allowed to execute
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunnington * this program.
3e96abd39343cc5e8f4bf8ff7429409658f0d484Phill Cunnington #define HTTPD_USER "www"
2feee3bd4482cbe7e4a8cf1a228bf17723b13934jeff.schenk * UID_MIN -- Define this as the lowest UID allowed to be a target user
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * for suEXEC. For most systems, 500 or 100 is common.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk #define UID_MIN 100
133bed8ec2ccc857a62d6301f67c3ef3d36aa333Peter Major * GID_MIN -- Define this as the lowest GID allowed to be a target group
89503929c8983c48e2049c77284b52e79ad37c32jeff.schenk * for suEXEC. For most systems, 100 is common.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk #define GID_MIN 100
1d03ac3e808c2c653316d01713105e209914fc81Neil Madden * USERDIR_SUFFIX -- Define to be the subdirectory under users'
1d03ac3e808c2c653316d01713105e209914fc81Neil Madden * home directories where suEXEC access should
13cf991efe018d84db08f3aaecf99bc62d97ecbejeff.schenk * be allowed. All executables under this directory
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * will be executable by suEXEC as the user so
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * they should be "safe" programs. If you are
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk * using a "simple" UserDir directive (ie. one
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk * without a "*" in it) this should be set to
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk * the same value. suEXEC will not work properly
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk * in cases where the UserDir directive points to
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk * a location that is not the same as the user's
d41212f2bd058e5d3d82771d9bbdb94481982f2bjeff.schenk * home directory as referenced in the passwd file.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * If you have VirtualHosts with a different
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * UserDir for each, you will need to define them to
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * all reside in one parent directory; then name that
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * parent directory here. IF THIS IS NOT DEFINED
c0202e5a338212ae386c672821f6dc4931c50f45James Phillpotts * PROPERLY, ~USERDIR CGI REQUESTS WILL NOT WORK!
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * See the suEXEC documentation for more detailed
3a1076834ccd4b3ecf4fac754b7ba662d4251020Allan Foster * information.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major #define USERDIR_SUFFIX "public_html"
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * LOG_EXEC -- Define this as a filename if you want all suEXEC
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * transactions and errors logged for auditing and
f720a6e4cf0eab17d4a0fc5177e85bb34fbfd74dPhill Cunnington * debugging purposes.
f720a6e4cf0eab17d4a0fc5177e85bb34fbfd74dPhill Cunnington #define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log" /* Need me? */
80ca0b9f5ad61b2335af25d4dcf25a04ebfcbc91Peter Major * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * will be the only hierarchy (aside from UserDirs)
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk * that can be used for suEXEC behavior.
84c335df5b56662ff61ec440ad718e29fca8460ajeff.schenk * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk #define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
d24287f6bf980f1960f3e76e4a1c8933ea26c182Peter Major<STRONG>COMPILING THE SUEXEC WRAPPER</STRONG><BR>
762dbed51cb99a0bddaa30954aaf41704f347b9fJake FeaselYou now need to compile the suEXEC wrapper. At the shell command prompt,
25e37495f2591ee8f2c057f2644ed5570b4c078dPeter Majortype: <STRONG><CODE>cc suexec.c -o suexec [ENTER]</CODE></STRONG>.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter MajorThis should create the <STRONG><em>suexec</em></STRONG> wrapper executable.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG>COMPILING APACHE FOR USE WITH SUEXEC</STRONG><BR>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkBy default, Apache is compiled to look for the suEXEC wrapper in the following
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk /* The path to the suEXEC wrapper */
ee24b491b9c8127b749e705bbef662b2ed8874dbjeff.schenk #define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
bd563314e425c4bf7675643269f2b4633ad39f42Allan FosterIf your installation requires location of the wrapper program in a different
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkdirectory, edit src/httpd.h and recompile your Apache server.
386650a8957e131311273ee84a4a4113ad5e3fe2Peter MajorSee <A HREF="install.html">Compiling and Installing Apache</A> for more
1563dad27ad07914e8f2ab1de04925eed4e188a4Peter Majorinfo on this process.
f56a278c148b90f6c2a675e0c1fa8686ca5abed4Robert Wapshott<STRONG>COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION</STRONG><BR>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkCopy the <STRONG><em>suexec</em></STRONG> executable created in the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkexercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenk<STRONG><CODE>cp suexec /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG>
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenkIn order for the wrapper to set the user ID, it must me installed as owner
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenk<STRONG><em>root</em></STRONG> and must have the setuserid execution bit
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenkset for file modes. If you are not running a <STRONG><em>root</em></STRONG>
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenkuser shell, do so now and execute the following commands.
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenk<STRONG><CODE>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG><BR>
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenk<STRONG><CODE>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG>
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenk<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenk<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3>
6ee60ad4ab4c8f9e97de533a60c32f7e5c61912bjeff.schenkAfter properly installing the <STRONG>suexec</STRONG> wrapper
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkexecutable, you must kill and restart the Apache server. A simple
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG><CODE>kill -1 `cat httpd.pid`</CODE></STRONG> will not be enough.
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenkUpon startup of the web-server, if Apache finds a properly configured
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenk<STRONG>suexec</STRONG> wrapper, it will print the following message to
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenk<CODE>Configuring Apache for use with suexec wrapper.</CODE>
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenkIf you don't see this message at server startup, the server is most
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenklikely not finding the wrapper program where it expects it, or the
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenkexecutable is not installed <STRONG><EM>setuid root</EM></STRONG>. Check
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenkyour installation and try again.
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter MajorOne way to use <STRONG>suEXEC</STRONG> is through the
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major<a href="mod/core.html#user"><STRONG>User</STRONG></a> and
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major<a href="mod/core.html#group"><STRONG>Group</STRONG></a> directives in
b61df94db8e71c225d3c3d9870894e4f6744ec69jeff.schenk<a href="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></a>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkdefinitions. By setting these directives to values different from the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkmain server user ID, all requests for CGI resources will be executed as
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkthe <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG><VirtualHost></STRONG>. If only one or
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkneither of these directives are specified for a
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG><VirtualHost></STRONG> then the main
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkserver userid is assumed.<p>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkthe user to which the request is being directed. This is accomplished by
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkusing the <STRONG>~</STRONG> character prefixing the user ID for whom
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkexecution is desired.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkThe only requirement needed for this feature to work is for CGI
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkexecution to be enabled for the user and that the script must meet the
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkscrutiny of the <a href="#model">security checks</a> above.
2251181c0efbc59bb60c175973f890345271518cPeter Major<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
2251181c0efbc59bb60c175973f890345271518cPeter MajorThe suEXEC wrapper will write log information to the location defined in
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkthe <code>suexec.h</code> as indicated above. If you feel you have
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkconfigured and installed the wrapper properly, have a look at this log
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill Cunningtonand the error_log for the server to see where you may have gone astray.
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill Cunnington<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill Cunnington<H3><A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A></H3>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<STRONG>NOTE!</STRONG> This section may not be complete. For the latest
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenkrevision of this section of the documentation, see the Apache Group's
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk<A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A>
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter MajorThere are a few points of interest regarding the wrapper that can cause
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenklimitations on server setup. Please review these before submitting any
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk"bugs" regarding suEXEC.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <LH><STRONG>suEXEC Points Of Interest</STRONG></LH>
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major <LI>Hierarchy limitations
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk <BLOCKQUOTE>
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig For security and efficiency reasons, all suexec requests must
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig remain within either a top-level document root for virtual
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig host requests, or one top-level personal document root for
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig userdir requests. For example, if you have four VirtualHosts
247203cf5bb5bc7e81871318633899d2c44416b0Mark Craig configured, you would need to structure all of your VHosts'
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk document roots off of one main Apache document hierarchy to
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk take advantage of suEXEC for VirtualHosts. (Example forthcoming.)
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk </BLOCKQUOTE>
caf8818e7c8d47b5aae8c69749e0970fc30d079ejenkins <LI>suEXEC's PATH environment variable
4706c25452067fd4a11ee6c6cb30a7b4135904f8Peter Major <BLOCKQUOTE>
4acf32c19b2198ca5a52c6d03d50b647ad6a0703Peter Major This can be a dangerous thing to change. Make certain every
64d3fa08513695d9a3c20bdd22593aa9d0d900b4Alin Brici path you include in this define is a <STRONG>trusted</STRONG>
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk directory. You don't want to open people up to having someone
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk from across the world running a trojan horse on them.
3133cf1b294fb4042826d58b24e4a2d0216d0349jeff.schenk </BLOCKQUOTE>
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major <LI>Altering the suEXEC code
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major <BLOCKQUOTE>
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major Again, this can cause <STRONG>Big Trouble</STRONG> if you try
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major this without knowing what you are doing. Stay away from it
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major if at all possible.
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major </BLOCKQUOTE>
79943d71bcf8d4933e74f29a1b0e87f8898508cbPeter Major<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
f720a6e4cf0eab17d4a0fc5177e85bb34fbfd74dPhill Cunnington<!--#include virtual="footer.html" -->