docs/manual/suexec.html.en - httpd - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <meta name="generator" content="HTML Tidy, see www.w3.org" />

     <title>Apache suEXEC Support</title>
   </head>
   <!-- Background white, links blue (unvisited), navy (visited), red (active) -->

   <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
   vlink="#000080" alink="#FF0000">
     <!--#include virtual="header.html" -->

     <h1 align="CENTER">Apache suEXEC Support</h1>

     <ol>
       <li><big><strong>CONTENTS</strong></big></li>

       <li><a href="#what">What is suEXEC?</a></li>

       <li><a href="#before">Before we begin.</a></li>

       <li><a href="#model">suEXEC Security Model.</a></li>

       <li><a href="#install">Configuring &amp; Installing
       suEXEC</a></li>

       <li><a href="#enable">Enabling &amp; Disabling
       suEXEC</a></li>

       <li><a href="#usage">Using suEXEC</a></li>

       <li><a href="#debug">Debugging suEXEC</a></li>

       <li><a href="#jabberwock">Beware the Jabberwock: Warnings
       &amp; Examples</a></li>
     </ol>
     <br />
      <br />


     <h3><a id="what" name="what">What is suEXEC?</a></h3>

     <p align="LEFT">The <strong>suEXEC</strong> feature --
     introduced in Apache 1.2 -- provides Apache users the ability
     to run <strong>CGI</strong> and <strong>SSI</strong> programs
     under user IDs different from the user ID of the calling
     web-server. Normally, when a CGI or SSI program executes, it
     runs as the same user who is running the web server.</p>

     <p align="LEFT">Used properly, this feature can reduce
     considerably the security risks involved with allowing users to
     develop and run private CGI or SSI programs. However, if suEXEC
     is improperly configured, it can cause any number of problems
     and possibly create new holes in your computer's security. If
     you aren't familiar with managing setuid root programs and the
     security issues they present, we highly recommend that you not
     consider using suEXEC.</p>

     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>

     <h3><a id="before" name="before">Before we begin.</a></h3>

     <p align="LEFT">Before jumping head-first into this document,
     you should be aware of the assumptions made on the part of the
     Apache Group and this document.</p>

     <p align="LEFT">First, it is assumed that you are using a UNIX
     derivate operating system that is capable of
     <strong>setuid</strong> and <strong>setgid</strong> operations.
     All command examples are given in this regard. Other platforms,
     if they are capable of supporting suEXEC, may differ in their
     configuration.</p>

     <p align="LEFT">Second, it is assumed you are familiar with
     some basic concepts of your computer's security and its
     administration. This involves an understanding of
     <strong>setuid/setgid</strong> operations and the various
     effects they may have on your system and its level of
     security.</p>

     <p align="LEFT">Third, it is assumed that you are using an
     <strong>unmodified</strong> version of suEXEC code. All code
     for suEXEC has been carefully scrutinized and tested by the
     developers as well as numerous beta testers. Every precaution
     has been taken to ensure a simple yet solidly safe base of
     code. Altering this code can cause unexpected problems and new
     security risks. It is <strong>highly</strong> recommended you
     not alter the suEXEC code unless you are well versed in the
     particulars of security programming and are willing to share
     your work with the Apache Group for consideration.</p>

     <p align="LEFT">Fourth, and last, it has been the decision of
     the Apache Group to <strong>NOT</strong> make suEXEC part of
     the default installation of Apache. To this end, suEXEC
     configuration requires of the administrator careful attention
     to details. After due consideration has been given to the
     various settings for suEXEC, the administrator may install
     suEXEC through normal installation methods. The values for
     these settings need to be carefully determined and specified by
     the administrator to properly maintain system security during
     the use of suEXEC functionality. It is through this detailed
     process that the Apache Group hopes to limit suEXEC
     installation only to those who are careful and determined
     enough to use it.</p>

     <p align="LEFT">Still with us? Yes? Good. Let's move on!</p>

     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>

     <h3><a id="model" name="model">suEXEC Security Model</a></h3>

     <p align="LEFT">Before we begin configuring and installing
     suEXEC, we will first discuss the security model you are about
     to implement. By doing so, you may better understand what
     exactly is going on inside suEXEC and what precautions are
     taken to ensure your system's security.</p>

     <p align="LEFT"><strong>suEXEC</strong> is based on a setuid
     "wrapper" program that is called by the main Apache web server.
     This wrapper is called when an HTTP request is made for a CGI
     or SSI program that the administrator has designated to run as
     a userid other than that of the main server. When such a
     request is made, Apache provides the suEXEC wrapper with the
     program's name and the user and group IDs under which the
     program is to execute.</p>

     <p align="LEFT">The wrapper then employs the following process
     to determine success or failure -- if any one of these
     conditions fail, the program logs the failure and exits with an
     error, otherwise it will continue:</p>

     <ol>
       <li>
         <strong>Was the wrapper called with the proper number of
         arguments?</strong>

         <blockquote>
           The wrapper will only execute if it is given the proper
           number of arguments. The proper argument format is known
           to the Apache web server. If the wrapper is not receiving
           the proper number of arguments, it is either being
           hacked, or there is something wrong with the suEXEC
           portion of your Apache binary.
         </blockquote>
       </li>

       <li>
         <strong>Is the user executing this wrapper a valid user of
         this system?</strong>

         <blockquote>
           This is to ensure that the user executing the wrapper is
           truly a user of the system.
         </blockquote>
       </li>

       <li>
         <strong>Is this valid user allowed to run the
         wrapper?</strong>

         <blockquote>
           Is this user the user allowed to run this wrapper? Only
           one user (the Apache user) is allowed to execute this
           program.
         </blockquote>
       </li>

       <li>
         <strong>Does the target program have an unsafe hierarchical
         reference?</strong>

         <blockquote>
           Does the target program contain a leading '/' or have a
           '..' backreference? These are not allowed; the target
           program must reside within the Apache webspace.
         </blockquote>
       </li>

       <li>
         <strong>Is the target user name valid?</strong>

         <blockquote>
           Does the target user exist?
         </blockquote>
       </li>

       <li>
         <strong>Is the target group name valid?</strong>

         <blockquote>
           Does the target group exist?
         </blockquote>
       </li>

       <li>
         <strong>Is the target user <em>NOT</em> superuser?</strong>


         <blockquote>
           Presently, suEXEC does not allow 'root' to execute
           CGI/SSI programs.
         </blockquote>
       </li>

       <li>
         <strong>Is the target userid <em>ABOVE</em> the minimum ID
         number?</strong>

         <blockquote>
           The minimum user ID number is specified during
           configuration. This allows you to set the lowest possible
           userid that will be allowed to execute CGI/SSI programs.
           This is useful to block out "system" accounts.
         </blockquote>
       </li>

       <li>
         <strong>Is the target group <em>NOT</em> the superuser
         group?</strong>

         <blockquote>
           Presently, suEXEC does not allow the 'root' group to
           execute CGI/SSI programs.
         </blockquote>
       </li>

       <li>
         <strong>Is the target groupid <em>ABOVE</em> the minimum ID
         number?</strong>

         <blockquote>
           The minimum group ID number is specified during
           configuration. This allows you to set the lowest possible
           groupid that will be allowed to execute CGI/SSI programs.
           This is useful to block out "system" groups.
         </blockquote>
       </li>

       <li>
         <strong>Can the wrapper successfully become the target user
         and group?</strong>

         <blockquote>
           Here is where the program becomes the target user and
           group via setuid and setgid calls. The group access list
           is also initialized with all of the groups of which the
           user is a member.
         </blockquote>
       </li>

       <li>
         <strong>Does the directory in which the program resides
         exist?</strong>

         <blockquote>
           If it doesn't exist, it can't very well contain files.
         </blockquote>
       </li>

       <li>
         <strong>Is the directory within the Apache
         webspace?</strong>

         <blockquote>
           If the request is for a regular portion of the server, is
           the requested directory within the server's document
           root? If the request is for a UserDir, is the requested
           directory within the user's document root?
         </blockquote>
       </li>

       <li>
         <strong>Is the directory <em>NOT</em> writable by anyone
         else?</strong>

         <blockquote>
           We don't want to open up the directory to others; only
           the owner user may be able to alter this directories
           contents.
         </blockquote>
       </li>

       <li>
         <strong>Does the target program exist?</strong>

         <blockquote>
           If it doesn't exists, it can't very well be executed.
         </blockquote>
       </li>

       <li>
         <strong>Is the target program <em>NOT</em> writable by
         anyone else?</strong>

         <blockquote>
           We don't want to give anyone other than the owner the
           ability to change the program.
         </blockquote>
       </li>

       <li>
         <strong>Is the target program <em>NOT</em> setuid or
         setgid?</strong>

         <blockquote>
           We do not want to execute programs that will then change
           our UID/GID again.
         </blockquote>
       </li>

       <li>
         <strong>Is the target user/group the same as the program's
         user/group?</strong>

         <blockquote>
           Is the user the owner of the file?
         </blockquote>
       </li>

       <li>
         <strong>Can we successfully clean the process environment
         to ensure safe operations?</strong>

         <blockquote>
           suEXEC cleans the process' environment by establishing a
           safe execution PATH (defined during configuration), as
           well as only passing through those variables whose names
           are listed in the safe environment list (also created
           during configuration).
         </blockquote>
       </li>

       <li>
         <strong>Can we successfully become the target program and
         execute?</strong>

         <blockquote>
           Here is where suEXEC ends and the target program begins.
         </blockquote>
       </li>
     </ol>
     <br />
      <br />


     <p align="LEFT">This is the standard operation of the the
     suEXEC wrapper's security model. It is somewhat stringent and
     can impose new limitations and guidelines for CGI/SSI design,
     but it was developed carefully step-by-step with security in
     mind.</p>

     <p align="LEFT">For more information as to how this security
     model can limit your possibilities in regards to server
     configuration, as well as what security risks can be avoided
     with a proper suEXEC setup, see the <a
     href="#jabberwock">"Beware the Jabberwock"</a> section of this
     document.</p>

     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>

     <h3><a id="install" name="install">Configuring &amp; Installing
     suEXEC</a></h3>

     <p align="LEFT">Here's where we begin the fun. If you use
     Apache 1.2 or prefer to configure Apache 1.3 with the
     "<code>src/Configure</code>" script you have to edit the suEXEC
     header file and install the binary in its proper location
     manually. The following sections describe the configuration and
     installation for Apache 1.3 with the AutoConf-style interface
     (APACI).</p>

     <p align="LEFT"><strong>APACI's suEXEC configuration
     options</strong><br />
     </p>

     <dl>
       <dt><code>--enable-suexec</code></dt>

       <dd>This option enables the suEXEC feature which is never
       installed or activated by default. At least one
       --suexec-xxxxx option has to be provided together with the
       --enable-suexec option to let APACI accept your request for
       using the suEXEC feature.</dd>

       <dt><code>--suexec-caller=<em>UID</em></code></dt>

       <dd>The <a href="mod/mpm_common.html#user">username</a> under which
       Apache normally runs. This is the only user allowed to
       execute this program.</dd>

       <dt><code>--suexec-docroot=<em>DIR</em></code></dt>

       <dd>Define as the DocumentRoot set for Apache. This will be
       the only hierarchy (aside from UserDirs) that can be used for
       suEXEC behavior. The default directory is the --datadir value
       with the suffix "/htdocs", <em>e.g.</em> if you configure
       with "<code>--datadir=/home/apache</code>" the directory
       "/home/apache/htdocs" is used as document root for the suEXEC
       wrapper.</dd>

       <dt><code>--suexec-logfile=<em>FILE</em></code></dt>

       <dd>This defines the filename to which all suEXEC
       transactions and errors are logged (useful for auditing and
       debugging purposes). By default the logfile is named
       "suexec_log" and located in your standard logfile directory
       (--logfiledir).</dd>

       <dt><code>--suexec-userdir=<em>DIR</em></code></dt>

       <dd>Define to be the subdirectory under users' home
       directories where suEXEC access should be allowed. All
       executables under this directory will be executable by suEXEC
       as the user so they should be "safe" programs. If you are
       using a "simple" UserDir directive (ie. one without a "*" in
       it) this should be set to the same value. suEXEC will not
       work properly in cases where the UserDir directive points to
       a location that is not the same as the user's home directory
       as referenced in the passwd file. Default value is
       "public_html".<br />
        If you have virtual hosts with a different UserDir for each,
       you will need to define them to all reside in one parent
       directory; then name that parent directory here. <strong>If
       this is not defined properly, "~userdir" cgi requests will
       not work!</strong></dd>

       <dt><code>--suexec-uidmin=<em>UID</em></code></dt>

       <dd>Define this as the lowest UID allowed to be a target user
       for suEXEC. For most systems, 500 or 100 is common. Default
       value is 100.</dd>

       <dt><code>--suexec-gidmin=<em>GID</em></code></dt>

       <dd>Define this as the lowest GID allowed to be a target
       group for suEXEC. For most systems, 100 is common and
       therefore used as default value.</dd>

       <dt><code>--suexec-safepath=<em>PATH</em></code></dt>

       <dd>Define a safe PATH environment to pass to CGI
       executables. Default value is
       "/usr/local/bin:/usr/bin:/bin".</dd>
     </dl>
     <br />
      <br />


     <p align="LEFT"><strong>Checking your suEXEC
     setup</strong><br />
      Before you compile and install the suEXEC wrapper you can
     check the configuration with the --layout option.<br />
      Example output:</p>
 <pre>
     suEXEC setup:
             suexec binary: /usr/local/apache/sbin/suexec
             document root: /usr/local/apache/share/htdocs
            userdir suffix: public_html
                   logfile: /usr/local/apache/var/log/suexec_log
                 safe path: /usr/local/bin:/usr/bin:/bin
                 caller ID: www
           minimum user ID: 100
          minimum group ID: 100
 </pre>
     <br />
      <br />


     <p align="LEFT"><strong>Compiling and installing the suEXEC
     wrapper</strong><br />
      If you have enabled the suEXEC feature with the
     --enable-suexec option the suexec binary (together with Apache
     itself) is automatically built if you execute the command
     "make".<br />
      After all components have been built you can execute the
     command "make install" to install them. The binary image
     "suexec" is installed in the directory defined by the --sbindir
     option. Default location is
     "/usr/local/apache/sbin/suexec".<br />
      Please note that you need <strong><em>root
     privileges</em></strong> for the installation step. In order
     for the wrapper to set the user ID, it must be installed as
     owner <code><em>root</em></code> and must have the setuserid
     execution bit set for file modes.</p>

     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>

     <h3><a id="enable" name="enable">Enabling &amp; Disabling
     suEXEC</a></h3>

     <p align="LEFT">Upon startup of Apache, it looks for the file
     "suexec" in the "sbin" directory (default is
     "/usr/local/apache/sbin/suexec"). If Apache finds a properly
     configured suEXEC wrapper, it will print the following message
     to the error log:</p>
 <pre>
     [notice] suEXEC mechanism enabled (wrapper: <em>/path/to/suexec</em>)
 </pre>
     If you don't see this message at server startup, the server is
     most likely not finding the wrapper program where it expects
     it, or the executable is not installed <em>setuid root</em>.
     <br />
      If you want to enable the suEXEC mechanism for the first time
     and an Apache server is already running you must kill and
     restart Apache. Restarting it with a simple HUP or USR1 signal
     will not be enough. <br />
      If you want to disable suEXEC you should kill and restart
     Apache after you have removed the "suexec" file. <br />
      <br />


     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>

     <h3><a id="usage" name="usage">Using suEXEC</a></h3>

     <p align="LEFT"><strong>Virtual Hosts:</strong><br />
      One way to use the suEXEC wrapper is through the <a
     href="mod/mpm_common.html#user">User</a> and <a
     href="mod/mpm_common.html#group">Group</a> directives in <a
     href="mod/core.html#virtualhost">VirtualHost</a> definitions.
     By setting these directives to values different from the main
     server user ID, all requests for CGI resources will be executed
     as the <em>User</em> and <em>Group</em> defined for that
     <code>&lt;VirtualHost&gt;</code>. If only one or neither of
     these directives are specified for a
     <code>&lt;VirtualHost&gt;</code> then the main server userid is
     assumed.</p>

     <p><strong>User directories:</strong><br />
      The suEXEC wrapper can also be used to execute CGI programs as
     the user to which the request is being directed. This is
     accomplished by using the "<strong><code>~</code></strong>"
     character prefixing the user ID for whom execution is desired.
     The only requirement needed for this feature to work is for CGI
     execution to be enabled for the user and that the script must
     meet the scrutiny of the <a href="#model">security checks</a>
     above.</p>

     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>

     <h3><a id="debug" name="debug">Debugging suEXEC</a></h3>

     <p align="LEFT">The suEXEC wrapper will write log information
     to the file defined with the --suexec-logfile option as
     indicated above. If you feel you have configured and installed
     the wrapper properly, have a look at this log and the error_log
     for the server to see where you may have gone astray.</p>

     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>

     <h3><a id="jabberwock" name="jabberwock">Beware the Jabberwock:
     Warnings &amp; Examples</a></h3>

     <p align="LEFT"><strong>NOTE!</strong> This section may not be
     complete. For the latest revision of this section of the
     documentation, see the Apache Group's <a
     href="http://www.apache.org/docs/suexec.html">Online
     Documentation</a> version.</p>

     <p align="LEFT">There are a few points of interest regarding
     the wrapper that can cause limitations on server setup. Please
     review these before submitting any "bugs" regarding suEXEC.</p>

     <ul>
       <li><strong>suEXEC Points Of Interest</strong></li>

       <li>
         Hierarchy limitations

         <blockquote>
           For security and efficiency reasons, all suexec requests
           must remain within either a top-level document root for
           virtual host requests, or one top-level personal document
           root for userdir requests. For example, if you have four
           VirtualHosts configured, you would need to structure all
           of your VHosts' document roots off of one main Apache
           document hierarchy to take advantage of suEXEC for
           VirtualHosts. (Example forthcoming.)
         </blockquote>
       </li>

       <li>
         suEXEC's PATH environment variable

         <blockquote>
           This can be a dangerous thing to change. Make certain
           every path you include in this define is a
           <strong>trusted</strong> directory. You don't want to
           open people up to having someone from across the world
           running a trojan horse on them.
         </blockquote>
       </li>

       <li>
         Altering the suEXEC code

         <blockquote>
           Again, this can cause <strong>Big Trouble</strong> if you
           try this without knowing what you are doing. Stay away
           from it if at all possible.
         </blockquote>
       </li>
     </ul>

     <p align="CENTER"><strong><a href="suexec.html">BACK TO
     CONTENTS</a></strong></p>
     <!--#include virtual="footer.html" -->
   </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta name="generator" content="HTML Tidy, see www.w3.org" />

	<title>Apache suEXEC Support</title>
	</head>
	<!-- Background white, links blue (unvisited), navy (visited), red (active) -->

	<body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
	vlink="#000080" alink="#FF0000">
	<!--#include virtual="header.html" -->

	<h1 align="CENTER">Apache suEXEC Support</h1>

	<ol>
	<li><big><strong>CONTENTS</strong></big></li>

	<li><a href="#what">What is suEXEC?</a></li>

	<li><a href="#before">Before we begin.</a></li>

	<li><a href="#model">suEXEC Security Model.</a></li>

	<li><a href="#install">Configuring & Installing
	suEXEC</a></li>

	<li><a href="#enable">Enabling & Disabling
	suEXEC</a></li>

	<li><a href="#usage">Using suEXEC</a></li>

	<li><a href="#debug">Debugging suEXEC</a></li>

	<li><a href="#jabberwock">Beware the Jabberwock: Warnings
	& Examples</a></li>
	</ol>
	<br />
	<br />


	<h3><a id="what" name="what">What is suEXEC?</a></h3>

	<p align="LEFT">The <strong>suEXEC</strong> feature --
	introduced in Apache 1.2 -- provides Apache users the ability
	to run <strong>CGI</strong> and <strong>SSI</strong> programs
	under user IDs different from the user ID of the calling
	web-server. Normally, when a CGI or SSI program executes, it
	runs as the same user who is running the web server.</p>

	<p align="LEFT">Used properly, this feature can reduce
	considerably the security risks involved with allowing users to
	develop and run private CGI or SSI programs. However, if suEXEC
	is improperly configured, it can cause any number of problems
	and possibly create new holes in your computer's security. If
	you aren't familiar with managing setuid root programs and the
	security issues they present, we highly recommend that you not
	consider using suEXEC.</p>

	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>

	<h3><a id="before" name="before">Before we begin.</a></h3>

	<p align="LEFT">Before jumping head-first into this document,
	you should be aware of the assumptions made on the part of the
	Apache Group and this document.</p>

	<p align="LEFT">First, it is assumed that you are using a UNIX
	derivate operating system that is capable of
	<strong>setuid</strong> and <strong>setgid</strong> operations.
	All command examples are given in this regard. Other platforms,
	if they are capable of supporting suEXEC, may differ in their
	configuration.</p>

	<p align="LEFT">Second, it is assumed you are familiar with
	some basic concepts of your computer's security and its
	administration. This involves an understanding of
	<strong>setuid/setgid</strong> operations and the various
	effects they may have on your system and its level of
	security.</p>

	<p align="LEFT">Third, it is assumed that you are using an
	<strong>unmodified</strong> version of suEXEC code. All code
	for suEXEC has been carefully scrutinized and tested by the
	developers as well as numerous beta testers. Every precaution
	has been taken to ensure a simple yet solidly safe base of
	code. Altering this code can cause unexpected problems and new
	security risks. It is <strong>highly</strong> recommended you
	not alter the suEXEC code unless you are well versed in the
	particulars of security programming and are willing to share
	your work with the Apache Group for consideration.</p>

	<p align="LEFT">Fourth, and last, it has been the decision of
	the Apache Group to <strong>NOT</strong> make suEXEC part of
	the default installation of Apache. To this end, suEXEC
	configuration requires of the administrator careful attention
	to details. After due consideration has been given to the
	various settings for suEXEC, the administrator may install
	suEXEC through normal installation methods. The values for
	these settings need to be carefully determined and specified by
	the administrator to properly maintain system security during
	the use of suEXEC functionality. It is through this detailed
	process that the Apache Group hopes to limit suEXEC
	installation only to those who are careful and determined
	enough to use it.</p>

	<p align="LEFT">Still with us? Yes? Good. Let's move on!</p>

	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>

	<h3><a id="model" name="model">suEXEC Security Model</a></h3>

	<p align="LEFT">Before we begin configuring and installing
	suEXEC, we will first discuss the security model you are about
	to implement. By doing so, you may better understand what
	exactly is going on inside suEXEC and what precautions are
	taken to ensure your system's security.</p>

	<p align="LEFT"><strong>suEXEC</strong> is based on a setuid
	"wrapper" program that is called by the main Apache web server.
	This wrapper is called when an HTTP request is made for a CGI
	or SSI program that the administrator has designated to run as
	a userid other than that of the main server. When such a
	request is made, Apache provides the suEXEC wrapper with the
	program's name and the user and group IDs under which the
	program is to execute.</p>

	<p align="LEFT">The wrapper then employs the following process
	to determine success or failure -- if any one of these
	conditions fail, the program logs the failure and exits with an
	error, otherwise it will continue:</p>

	<ol>
	<li>
	<strong>Was the wrapper called with the proper number of
	arguments?</strong>

	<blockquote>
	The wrapper will only execute if it is given the proper
	number of arguments. The proper argument format is known
	to the Apache web server. If the wrapper is not receiving
	the proper number of arguments, it is either being
	hacked, or there is something wrong with the suEXEC
	portion of your Apache binary.
	</blockquote>
	</li>

	<li>
	<strong>Is the user executing this wrapper a valid user of
	this system?</strong>

	<blockquote>
	This is to ensure that the user executing the wrapper is
	truly a user of the system.
	</blockquote>
	</li>

	<li>
	<strong>Is this valid user allowed to run the
	wrapper?</strong>

	<blockquote>
	Is this user the user allowed to run this wrapper? Only
	one user (the Apache user) is allowed to execute this
	program.
	</blockquote>
	</li>

	<li>
	<strong>Does the target program have an unsafe hierarchical
	reference?</strong>

	<blockquote>
	Does the target program contain a leading '/' or have a
	'..' backreference? These are not allowed; the target
	program must reside within the Apache webspace.
	</blockquote>
	</li>

	<li>
	<strong>Is the target user name valid?</strong>

	<blockquote>
	Does the target user exist?
	</blockquote>
	</li>

	<li>
	<strong>Is the target group name valid?</strong>

	<blockquote>
	Does the target group exist?
	</blockquote>
	</li>

	<li>
	<strong>Is the target user <em>NOT</em> superuser?</strong>


	<blockquote>
	Presently, suEXEC does not allow 'root' to execute
	CGI/SSI programs.
	</blockquote>
	</li>

	<li>
	<strong>Is the target userid <em>ABOVE</em> the minimum ID
	number?</strong>

	<blockquote>
	The minimum user ID number is specified during
	configuration. This allows you to set the lowest possible
	userid that will be allowed to execute CGI/SSI programs.
	This is useful to block out "system" accounts.
	</blockquote>
	</li>

	<li>
	<strong>Is the target group <em>NOT</em> the superuser
	group?</strong>

	<blockquote>
	Presently, suEXEC does not allow the 'root' group to
	execute CGI/SSI programs.
	</blockquote>
	</li>

	<li>
	<strong>Is the target groupid <em>ABOVE</em> the minimum ID
	number?</strong>

	<blockquote>
	The minimum group ID number is specified during
	configuration. This allows you to set the lowest possible
	groupid that will be allowed to execute CGI/SSI programs.
	This is useful to block out "system" groups.
	</blockquote>
	</li>

	<li>
	<strong>Can the wrapper successfully become the target user
	and group?</strong>

	<blockquote>
	Here is where the program becomes the target user and
	group via setuid and setgid calls. The group access list
	is also initialized with all of the groups of which the
	user is a member.
	</blockquote>
	</li>

	<li>
	<strong>Does the directory in which the program resides
	exist?</strong>

	<blockquote>
	If it doesn't exist, it can't very well contain files.
	</blockquote>
	</li>

	<li>
	<strong>Is the directory within the Apache
	webspace?</strong>

	<blockquote>
	If the request is for a regular portion of the server, is
	the requested directory within the server's document
	root? If the request is for a UserDir, is the requested
	directory within the user's document root?
	</blockquote>
	</li>

	<li>
	<strong>Is the directory <em>NOT</em> writable by anyone
	else?</strong>

	<blockquote>
	We don't want to open up the directory to others; only
	the owner user may be able to alter this directories
	contents.
	</blockquote>
	</li>

	<li>
	<strong>Does the target program exist?</strong>

	<blockquote>
	If it doesn't exists, it can't very well be executed.
	</blockquote>
	</li>

	<li>
	<strong>Is the target program <em>NOT</em> writable by
	anyone else?</strong>

	<blockquote>
	We don't want to give anyone other than the owner the
	ability to change the program.
	</blockquote>
	</li>

	<li>
	<strong>Is the target program <em>NOT</em> setuid or
	setgid?</strong>

	<blockquote>
	We do not want to execute programs that will then change
	our UID/GID again.
	</blockquote>
	</li>

	<li>
	<strong>Is the target user/group the same as the program's
	user/group?</strong>

	<blockquote>
	Is the user the owner of the file?
	</blockquote>
	</li>

	<li>
	<strong>Can we successfully clean the process environment
	to ensure safe operations?</strong>

	<blockquote>
	suEXEC cleans the process' environment by establishing a
	safe execution PATH (defined during configuration), as
	well as only passing through those variables whose names
	are listed in the safe environment list (also created
	during configuration).
	</blockquote>
	</li>

	<li>
	<strong>Can we successfully become the target program and
	execute?</strong>

	<blockquote>
	Here is where suEXEC ends and the target program begins.
	</blockquote>
	</li>
	</ol>
	<br />
	<br />


	<p align="LEFT">This is the standard operation of the the
	suEXEC wrapper's security model. It is somewhat stringent and
	can impose new limitations and guidelines for CGI/SSI design,
	but it was developed carefully step-by-step with security in
	mind.</p>

	<p align="LEFT">For more information as to how this security
	model can limit your possibilities in regards to server
	configuration, as well as what security risks can be avoided
	with a proper suEXEC setup, see the <a
	href="#jabberwock">"Beware the Jabberwock"</a> section of this
	document.</p>

	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>

	<h3><a id="install" name="install">Configuring & Installing
	suEXEC</a></h3>

	<p align="LEFT">Here's where we begin the fun. If you use
	Apache 1.2 or prefer to configure Apache 1.3 with the
	"<code>src/Configure</code>" script you have to edit the suEXEC
	header file and install the binary in its proper location
	manually. The following sections describe the configuration and
	installation for Apache 1.3 with the AutoConf-style interface
	(APACI).</p>

	<p align="LEFT"><strong>APACI's suEXEC configuration
	options</strong><br />
	</p>

	<dl>
	<dt><code>--enable-suexec</code></dt>

	<dd>This option enables the suEXEC feature which is never
	installed or activated by default. At least one
	--suexec-xxxxx option has to be provided together with the
	--enable-suexec option to let APACI accept your request for
	using the suEXEC feature.</dd>

	<dt><code>--suexec-caller=<em>UID</em></code></dt>

	<dd>The <a href="mod/mpm_common.html#user">username</a> under which
	Apache normally runs. This is the only user allowed to
	execute this program.</dd>

	<dt><code>--suexec-docroot=<em>DIR</em></code></dt>

	<dd>Define as the DocumentRoot set for Apache. This will be
	the only hierarchy (aside from UserDirs) that can be used for
	suEXEC behavior. The default directory is the --datadir value
	with the suffix "/htdocs", <em>e.g.</em> if you configure
	with "<code>--datadir=/home/apache</code>" the directory
	"/home/apache/htdocs" is used as document root for the suEXEC
	wrapper.</dd>

	<dt><code>--suexec-logfile=<em>FILE</em></code></dt>

	<dd>This defines the filename to which all suEXEC
	transactions and errors are logged (useful for auditing and
	debugging purposes). By default the logfile is named
	"suexec_log" and located in your standard logfile directory
	(--logfiledir).</dd>

	<dt><code>--suexec-userdir=<em>DIR</em></code></dt>

	<dd>Define to be the subdirectory under users' home
	directories where suEXEC access should be allowed. All
	executables under this directory will be executable by suEXEC
	as the user so they should be "safe" programs. If you are
	using a "simple" UserDir directive (ie. one without a "*" in
	it) this should be set to the same value. suEXEC will not
	work properly in cases where the UserDir directive points to
	a location that is not the same as the user's home directory
	as referenced in the passwd file. Default value is
	"public_html".<br />
	If you have virtual hosts with a different UserDir for each,
	you will need to define them to all reside in one parent
	directory; then name that parent directory here. <strong>If
	this is not defined properly, "~userdir" cgi requests will
	not work!</strong></dd>

	<dt><code>--suexec-uidmin=<em>UID</em></code></dt>

	<dd>Define this as the lowest UID allowed to be a target user
	for suEXEC. For most systems, 500 or 100 is common. Default
	value is 100.</dd>

	<dt><code>--suexec-gidmin=<em>GID</em></code></dt>

	<dd>Define this as the lowest GID allowed to be a target
	group for suEXEC. For most systems, 100 is common and
	therefore used as default value.</dd>

	<dt><code>--suexec-safepath=<em>PATH</em></code></dt>

	<dd>Define a safe PATH environment to pass to CGI
	executables. Default value is
	"/usr/local/bin:/usr/bin:/bin".</dd>
	</dl>
	<br />
	<br />


	<p align="LEFT"><strong>Checking your suEXEC
	setup</strong><br />
	Before you compile and install the suEXEC wrapper you can
	check the configuration with the --layout option.<br />
	Example output:</p>
	<pre>
	suEXEC setup:
	suexec binary: /usr/local/apache/sbin/suexec
	document root: /usr/local/apache/share/htdocs
	userdir suffix: public_html
	logfile: /usr/local/apache/var/log/suexec_log
	safe path: /usr/local/bin:/usr/bin:/bin
	caller ID: www
	minimum user ID: 100
	minimum group ID: 100
	</pre>
	<br />
	<br />


	<p align="LEFT"><strong>Compiling and installing the suEXEC
	wrapper</strong><br />
	If you have enabled the suEXEC feature with the
	--enable-suexec option the suexec binary (together with Apache
	itself) is automatically built if you execute the command
	"make".<br />
	After all components have been built you can execute the
	command "make install" to install them. The binary image
	"suexec" is installed in the directory defined by the --sbindir
	option. Default location is
	"/usr/local/apache/sbin/suexec".<br />
	Please note that you need <strong><em>root
	privileges</em></strong> for the installation step. In order
	for the wrapper to set the user ID, it must be installed as
	owner <code><em>root</em></code> and must have the setuserid
	execution bit set for file modes.</p>

	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>

	<h3><a id="enable" name="enable">Enabling & Disabling
	suEXEC</a></h3>

	<p align="LEFT">Upon startup of Apache, it looks for the file
	"suexec" in the "sbin" directory (default is
	"/usr/local/apache/sbin/suexec"). If Apache finds a properly
	configured suEXEC wrapper, it will print the following message
	to the error log:</p>
	<pre>
	[notice] suEXEC mechanism enabled (wrapper: <em>/path/to/suexec</em>)
	</pre>
	If you don't see this message at server startup, the server is
	most likely not finding the wrapper program where it expects
	it, or the executable is not installed <em>setuid root</em>.
	<br />
	If you want to enable the suEXEC mechanism for the first time
	and an Apache server is already running you must kill and
	restart Apache. Restarting it with a simple HUP or USR1 signal
	will not be enough. <br />
	If you want to disable suEXEC you should kill and restart
	Apache after you have removed the "suexec" file. <br />
	<br />


	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>

	<h3><a id="usage" name="usage">Using suEXEC</a></h3>

	<p align="LEFT"><strong>Virtual Hosts:</strong><br />
	One way to use the suEXEC wrapper is through the <a
	href="mod/mpm_common.html#user">User</a> and <a
	href="mod/mpm_common.html#group">Group</a> directives in <a
	href="mod/core.html#virtualhost">VirtualHost</a> definitions.
	By setting these directives to values different from the main
	server user ID, all requests for CGI resources will be executed
	as the <em>User</em> and <em>Group</em> defined for that
	<code><VirtualHost></code>. If only one or neither of
	these directives are specified for a
	<code><VirtualHost></code> then the main server userid is
	assumed.</p>

	<p><strong>User directories:</strong><br />
	The suEXEC wrapper can also be used to execute CGI programs as
	the user to which the request is being directed. This is
	accomplished by using the "<strong><code>~</code></strong>"
	character prefixing the user ID for whom execution is desired.
	The only requirement needed for this feature to work is for CGI
	execution to be enabled for the user and that the script must
	meet the scrutiny of the <a href="#model">security checks</a>
	above.</p>

	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>

	<h3><a id="debug" name="debug">Debugging suEXEC</a></h3>

	<p align="LEFT">The suEXEC wrapper will write log information
	to the file defined with the --suexec-logfile option as
	indicated above. If you feel you have configured and installed
	the wrapper properly, have a look at this log and the error_log
	for the server to see where you may have gone astray.</p>

	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>

	<h3><a id="jabberwock" name="jabberwock">Beware the Jabberwock:
	Warnings & Examples</a></h3>

	<p align="LEFT"><strong>NOTE!</strong> This section may not be
	complete. For the latest revision of this section of the
	documentation, see the Apache Group's <a
	href="http://www.apache.org/docs/suexec.html">Online
	Documentation</a> version.</p>

	<p align="LEFT">There are a few points of interest regarding
	the wrapper that can cause limitations on server setup. Please
	review these before submitting any "bugs" regarding suEXEC.</p>

	<ul>
	<li><strong>suEXEC Points Of Interest</strong></li>

	<li>
	Hierarchy limitations

	<blockquote>
	For security and efficiency reasons, all suexec requests
	must remain within either a top-level document root for
	virtual host requests, or one top-level personal document
	root for userdir requests. For example, if you have four
	VirtualHosts configured, you would need to structure all
	of your VHosts' document roots off of one main Apache
	document hierarchy to take advantage of suEXEC for
	VirtualHosts. (Example forthcoming.)
	</blockquote>
	</li>

	<li>
	suEXEC's PATH environment variable

	<blockquote>
	This can be a dangerous thing to change. Make certain
	every path you include in this define is a
	<strong>trusted</strong> directory. You don't want to
	open people up to having someone from across the world
	running a trojan horse on them.
	</blockquote>
	</li>

	<li>
	Altering the suEXEC code

	<blockquote>
	Again, this can cause <strong>Big Trouble</strong> if you
	try this without knowing what you are doing. Stay away
	from it if at all possible.
	</blockquote>
	</li>
	</ul>

	<p align="CENTER"><strong><a href="suexec.html">BACK TO
	CONTENTS</a></strong></p>
	<!--#include virtual="footer.html" -->
	</body>
	</html>