suexec.html revision 34d4c19d15fb58f61d221a82015d672698ecef12
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt BGCOLOR="#FFFFFF"
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt TEXT="#000000"
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt LINK="#0000FF"
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt VLINK="#000080"
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt ALINK="#FF0000"
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<!--#include virtual="header.html" -->
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><A HREF="#model">suEXEC Security Model.</A></LI>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings &
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntApache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntprograms under user IDs different from the user ID of the calling web-server.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntNormally, when a CGI or SSI program executes, it runs as the same user who is
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntrunning the web server.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan HuntUsed properly, this feature can reduce considerably the security risks involved
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntwith allowing users to develop and run private CGI or SSI programs. However,
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntif suEXEC is improperly configured, it can cause any number of problems and
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntpossibly create new holes in your computer's security. If you aren't familiar
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntwith managing setuid root programs and the security issues they present, we
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunthighly recommend that you not consider using suEXEC.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntBefore jumping head-first into this document, you should be aware of the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntassumptions made on the part of the Apache Group and this document.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsFirst, it is assumed that you are using a UNIX derivate operating system that
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsis capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsAll command examples are given in this regard. Other platforms, if they are
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewscapable of supporting suEXEC, may differ in their configuration.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsSecond, it is assumed you are familiar with some basic concepts of your
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewscomputer's security and its administration. This involves an understanding
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsof <STRONG>setuid/setgid</STRONG> operations and the various effects they
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsmay have on your system and its level of security.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsThird, it is assumed that you are using an <STRONG>unmodified</STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsversion of suEXEC code. All code for suEXEC has been carefully scrutinized and
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewstested by the developers as well as numerous beta testers. Every precaution
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewshas been taken to ensure a simple yet solidly safe base of code. Altering this
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewscode can cause unexpected problems and new security risks. It is
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsare well versed in the particulars of security programming and are willing to
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsshare your work with the Apache Group for consideration.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsFourth, and last, it has been the decision of the Apache Group to
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsTo this end, suEXEC configuration requires of the administrator careful
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsattention to details. After due consideration has been given to the various
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewssettings for suEXEC, the administrator may install suEXEC through normal
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsinstallation methods. The values for these settings need to be carefully
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsdetermined and specified by the administrator to properly maintain system
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewssecurity during the use of suEXEC functionality. It is through this detailed
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsprocess that the Apache Group hopes to limit suEXEC installation only to those
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewswho are careful and determined enough to use it.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsStill with us? Yes? Good. Let's move on!
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<H3><A NAME="model">suEXEC Security Model</A></H3>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan HuntBefore we begin configuring and installing suEXEC, we will first discuss
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntthe security model you are about to implement. By doing so, you may
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntbetter understand what exactly is going on inside suEXEC and what precautions
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntare taken to ensure your system's security.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>suEXEC</STRONG> is based on a setuid "wrapper" program that is
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewscalled by the main Apache web server. This wrapper is called when an HTTP
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsrequest is made for a CGI or SSI program that the administrator has designated
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntto run as a userid other than that of the main server. When such a request
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntis made, Apache provides the suEXEC wrapper with the program's name and the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntuser and group IDs under which the program is to execute.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe wrapper then employs the following process to determine success or
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntfailure -- if any one of these conditions fail, the program logs the failure
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntand exits with an error, otherwise it will continue:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Was the wrapper called with the proper number of
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt arguments?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews The wrapper will only execute if it is given the proper number of arguments.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews The proper argument format is known to the Apache web server. If the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt is not receiving the proper number of arguments, it is either being hacked,
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt there is something wrong with the suEXEC portion of your Apache binary.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Is the user executing this wrapper a valid user of this
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt system?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt This is to ensure that the user executing the wrapper is truly a user of the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Is this user the user allowed to run this wrapper? Only one user (the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Apache user) is allowed to execute this program.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <LI><STRONG>Does the target program have an unsafe hierarchical
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews reference?</STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews Does the target program contain a leading '/' or have a '..' backreference?
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews These are not allowed; the target program must reside within the Apache
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <LI><STRONG>Is the target user name valid?</STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews Does the target user exist?
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews </BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <LI><STRONG>Is the target group name valid?</STRONG>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Does the target group exist?
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews </BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Presently, suEXEC does not allow 'root' to execute CGI/SSI programs.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt number?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt The minimum user ID number is specified during configuration. This allows
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt to set the lowest possible userid that will be allowed to execute CGI/SSI
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt programs. This is useful to block out "system" accounts.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Presently, suEXEC does not allow the 'root' group to execute CGI/SSI
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt number?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews The minimum group ID number is specified during configuration. This allows
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt to set the lowest possible groupid that will be allowed to execute CGI/SSI
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt programs. This is useful to block out "system" groups.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Can the wrapper successfully become the target user and
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt group?</STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews Here is where the program becomes the target user and group via setuid and
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt calls. The group access list is also initialized with all of the groups
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt the user is a member.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Does the directory in which the program resides exist?</STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews If it doesn't exist, it can't very well contain files.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Is the directory within the Apache webspace?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt If the request is for a regular portion of the server, is the requested
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt within the server's document root? If the request is for a UserDir, is
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews the requested
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt directory within the user's document root?
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews We don't want to open up the directory to others; only the owner user
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt to alter this directories contents.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Does the target program exist?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt If it doesn't exists, it can't very well be executed.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt else?</STRONG>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt We don't want to give anyone other than the owner the ability to
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt change the program.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt We do not want to execute programs that will then change our UID/GID again.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Is the target user/group the same as the program's
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Is the user the owner of the file?
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Can we successfully clean the process environment to
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt ensure safe operations?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt suEXEC cleans the process' environment by establishing a safe
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt execution PATH (defined
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt during configuration), as well as only passing through those
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt variables whose names
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt are listed in the safe environment list (also created during
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews configuration).
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <LI><STRONG>Can we successfully become the target program and
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt execute?</STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt <BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Here is where suEXEC ends and the target program begins.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt </BLOCKQUOTE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThis is the standard operation of the the suEXEC wrapper's security model.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan HuntIt is somewhat stringent and can impose new limitations and guidelines for
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsCGI/SSI design, but it was developed carefully step-by-step with security
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsFor more information as to how this security model can limit your possibilities
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsin regards to server configuration, as well as what security risks can be
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntavoided with a proper suEXEC setup, see the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntsection of this document.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt<H3><A NAME="install">Configuring & Installing suEXEC</A></H3>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan HuntHere's where we begin the fun. The configuration and installation of suEXEC is
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunta four step process: edit the suEXEC header file, compile suEXEC, place the
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntsuEXEC binary in its proper location, and configure Apache for use with suEXEC.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<STRONG>EDITING THE SUEXEC HEADER FILE</STRONG><BR>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt- From the top-level of the Apache source tree, type:
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><CODE>cd support [ENTER]</CODE></STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntEdit the <CODE>suexec.h</CODE> file and change the following macros to
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntmatch your local Apache installation.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * HTTPD_USER -- Define as the username under which Apache normally
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * runs. This is the only user allowed to execute
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * this program.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt #define HTTPD_USER "www"
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * UID_MIN -- Define this as the lowest UID allowed to be a target user
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * for suEXEC. For most systems, 500 or 100 is common.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt #define UID_MIN 100
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * GID_MIN -- Define this as the lowest GID allowed to be a target group
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * for suEXEC. For most systems, 100 is common.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews #define GID_MIN 100
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * USERDIR_SUFFIX -- Define to be the subdirectory under users'
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * home directories where suEXEC access should
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * be allowed. All executables under this directory
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * will be executable by suEXEC as the user so
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * they should be "safe" programs. If you are
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * using a "simple" UserDir directive (ie. one
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * without a "*" in it) this should be set to
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * the same value. suEXEC will not work properly
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * in cases where the UserDir directive points to
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * a location that is not the same as the user's
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * home directory as referenced in the passwd file.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * If you have VirtualHosts with a different
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * UserDir for each, you will need to define them to
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * all reside in one parent directory; then name that
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * parent directory here. IF THIS IS NOT DEFINED
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * PROPERLY, ~USERDIR CGI REQUESTS WILL NOT WORK!
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * See the suEXEC documentation for more detailed
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * information.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews #define USERDIR_SUFFIX "public_html"
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * LOG_EXEC -- Define this as a filename if you want all suEXEC
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * transactions and errors logged for auditing and
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt * debugging purposes.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews #define LOG_EXEC "/usr/local/apache/logs/cgi.log" /* Need me? */
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * will be the only hierarchy (aside from UserDirs)
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * that can be used for suEXEC behavior.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>COMPILING THE SUEXEC WRAPPER</STRONG><BR>
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsYou now need to compile the suEXEC wrapper. At the shell command prompt,
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsafter compiling Apache,
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewstype: <STRONG><CODE>make suexec[ENTER]</CODE></STRONG>.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsThis should create the <STRONG><EM>suexec</EM></STRONG> wrapper executable.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>COMPILING APACHE FOR USE WITH SUEXEC</STRONG><BR>
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsBy default, Apache is compiled to look for the suEXEC wrapper in the following
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews /* The path to the suExec wrapper, can be overridden in Configuration */
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews #ifndef SUEXEC_BIN
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsIf your installation requires location of the wrapper program in a different
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsdirectory, either add <CODE>-DSUEXEC_BIN=\"<EM></your/path/to/suexec></EM>\"</CODE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsto your CFLAGS (or edit src/include/httpd.h) and recompile your Apache server.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsSee <A HREF="install.html">Compiling and Installing Apache</A>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews(and the <SAMP>INSTALL</SAMP> file in the source distribution)
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsfor more info on this process.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION</STRONG><BR>
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsCopy the <STRONG><EM>suexec</EM></STRONG> executable created in the
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsexercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><CODE>cp suexec /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntIn order for the wrapper to set the user ID, it must me installed as owner
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<STRONG><EM>root</EM></STRONG> and must have the setuserid execution bit
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsset for file modes. If you are not running a <STRONG><EM>root</EM></STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsuser shell, do so now and execute the following commands.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><CODE>chown root /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><CODE>chmod 4711 /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3>
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntAfter properly installing the <STRONG>suexec</STRONG> wrapper
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntexecutable, you must kill and restart the Apache server. A simple
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<STRONG><CODE>kill -1 `cat httpd.pid`</CODE></STRONG> will not be enough.
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsUpon startup of the web-server, if Apache finds a properly configured
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>suexec</STRONG> wrapper, it will print the following message to
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<CODE>Configuring Apache for use with suexec wrapper.</CODE>
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntIf you don't see this message at server startup, the server is most
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntlikely not finding the wrapper program where it expects it, or the
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsexecutable is not installed <STRONG><EM>setuid root</EM></STRONG>. Check
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntyour installation and try again.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntOne way to use <STRONG>suEXEC</STRONG> is through the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<A HREF="mod/core.html#user"><STRONG>User</STRONG></A> and
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<A HREF="mod/core.html#group"><STRONG>Group</STRONG></A> directives in
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<A HREF="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></A>
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdefinitions. By setting these directives to values different from the
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsmain server user ID, all requests for CGI resources will be executed as
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntthe <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt<STRONG><VirtualHost></STRONG>. If only one or
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsneither of these directives are specified for a
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><VirtualHost></STRONG> then the main
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsserver userid is assumed.<P>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntthe user to which the request is being directed. This is accomplished by
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsusing the <STRONG>~</STRONG> character prefixing the user ID for whom
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntexecution is desired.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe only requirement needed for this feature to work is for CGI
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntexecution to be enabled for the user and that the script must meet the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntscrutiny of the <A HREF="#model">security checks</A> above.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsThe suEXEC wrapper will write log information to the location defined in
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsthe <CODE>suexec.h</CODE> as indicated above. If you feel you have
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsconfigured and installed the wrapper properly, have a look at this log
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsand the error_log for the server to see where you may have gone astray.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<STRONG>NOTE!</STRONG> This section may not be complete. For the latest
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewsrevision of this section of the documentation, see the Apache Group's
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews<A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A>
4a53e3c2b83c476a93148eaee0272649beb221caMark AndrewsThere are a few points of interest regarding the wrapper that can cause
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrewslimitations on server setup. Please review these before submitting any
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews"bugs" regarding suEXEC.
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <LI><STRONG>suEXEC Points Of Interest</STRONG></LI>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <LI>Hierarchy limitations
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews <BLOCKQUOTE>
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews For security and efficiency reasons, all suexec requests must
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews remain within either a top-level document root for virtual
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews host requests, or one top-level personal document root for
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews userdir requests. For example, if you have four VirtualHosts
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews configured, you would need to structure all of your VHosts'
4a53e3c2b83c476a93148eaee0272649beb221caMark Andrews document roots off of one main Apache document hierarchy to
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt take advantage of suEXEC for VirtualHosts. (Example forthcoming.)
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <LI>suEXEC's PATH environment variable
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt This can be a dangerous thing to change. Make certain every
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt path you include in this define is a <STRONG>trusted</STRONG>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt directory. You don't want to open people up to having someone
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt from across the world running a trojan horse on them.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <LI>Altering the suEXEC code
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt <BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Again, this can cause <STRONG>Big Trouble</STRONG> if you try
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt this without knowing what you are doing. Stay away from it
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt if at all possible.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt </BLOCKQUOTE>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt<!--#include virtual="footer.html" -->