httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@apache.org
Subject cvs commit: httpd-2.0/docs/manual suexec.xml suexec.html.en
Date Fri, 16 Aug 2002 03:49:25 GMT
slive       2002/08/15 20:49:24

  Modified:    docs/manual suexec.html.en
  Added:       docs/manual suexec.xml
  Log:
  New XML.
  
  Revision  Changes    Path
  1.32      +80 -164   httpd-2.0/docs/manual/suexec.html.en
  
  Index: suexec.html.en
  ===================================================================
  RCS file: /home/cvs/httpd-2.0/docs/manual/suexec.html.en,v
  retrieving revision 1.31
  retrieving revision 1.32
  diff -u -d -b -u -r1.31 -r1.32
  --- suexec.html.en	25 Jul 2002 21:46:38 -0000	1.31
  +++ suexec.html.en	16 Aug 2002 03:49:24 -0000	1.32
  @@ -1,56 +1,16 @@
  -<!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 provides
  +<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><!--
  +        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  +              This file is generated from xml source: DO NOT EDIT
  +        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  +      --><title>suEXEC Support - Apache HTTP Server</title><link href="./style/manual.css"
type="text/css" rel="stylesheet"></head><body><blockquote><div align="center"><img
src="./images/sub.gif" alt="[APACHE DOCUMENTATION]"><h3>Apache HTTP Server Version
2.0</h3></div><h1 align="center">suEXEC Support</h1>
  +    <p>The <strong>suEXEC</strong> feature 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
  +    <p>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
  @@ -58,31 +18,30 @@
       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>
  +  <ul><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></ul><hr><h2><a
name="before">Before we begin</a></h2>
   
  -    <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,
  +    <p>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
  +    <p>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
  +    <p>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
  +    <p>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
  @@ -93,7 +52,7 @@
       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
  +    <p>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
  @@ -107,20 +66,16 @@
       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>Still with us? Yes? Good. Let's move on!</p>
  +<h2><a name="model">suEXEC Security Model</a></h2>
   
  -    <p align="left">Before we begin configuring and installing
  +    <p>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
  +    <p><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
  @@ -129,7 +84,7 @@
       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
  +    <p>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>
  @@ -344,33 +299,25 @@
           </blockquote>
         </li>
       </ol>
  -    <br />
  -     <br />
  -     
   
  -    <p align="left">This is the standard operation of the the
  +    <p>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
  +    <p>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
  +    with a proper suEXEC setup, see the <a href="#jabberwock">"Beware the Jabberwock"</a>
section of this
       document.</p>
  +<h2><a name="install">Configuring &amp; Installing
  +    suEXEC</a></h2>
   
  -    <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.</p>
  +    <p>Here's where we begin the fun.</p>
   
  -    <p align="left"><strong>suEXEC configuration
  -    options</strong><br />
  +    <p><strong>suEXEC configuration
  +    options</strong><br>
       </p>
   
       <dl>
  @@ -406,7 +353,7 @@
         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 />
  +      "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
  @@ -449,93 +396,75 @@
         executables. Default value is
         "/usr/local/bin:/usr/bin:/bin".</dd>
       </dl>
  -    <br />
  -     <br />
        
  -
  -    <p align="left"><strong>Checking your suEXEC
  -    setup</strong><br />
  +    <p><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 />
  +    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 />
        
  +<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
  +    suEXEC setup:<br>
  +            suexec binary: /usr/local/apache/sbin/suexec<br>
  +            document root: /usr/local/apache/share/htdocs<br>
  +           userdir suffix: public_html<br>
  +                  logfile: /usr/local/apache/var/log/suexec_log<br>
  +                safe path: /usr/local/bin:/usr/bin:/bin<br>
  +                caller ID: www<br>
  +          minimum user ID: 100<br>
  +         minimum group ID: 100<br>
  +</code></td></tr></table></blockquote>
   
  -    <p align="left"><strong>Compiling and installing the suEXEC
  -    wrapper</strong><br />
  +    <p><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 />
  +    "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 />
  +    "/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>
  +<h2><a name="enable">Enabling &amp; Disabling
  +    suEXEC</a></h2>
   
  -    <p align="left">Upon startup of Apache, it looks for the file
  +    <p>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>
  +<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
       [notice] suEXEC mechanism enabled (wrapper: <em>/path/to/suexec</em>)
  -</pre>
  -    If you don't see this message at server startup, the server is
  +</code></td></tr></table></blockquote>
  +    <p>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
  +    it, or the executable is not installed <em>setuid root</em>.</p>
  +
  +     <p>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>
  +    will not be enough. </p>
  +     <p>If you want to disable suEXEC you should kill and restart
  +    Apache after you have removed the "suexec" file. </p>
  +<h2><a name="usage">Using suEXEC</a></h2>
   
  -    <p align="left"><strong>Virtual Hosts:</strong><br />
  -     One way to use the suEXEC wrapper is through the <a
  -    href="mod/mod_suexec.html#suexecusergroup">SuexecUserGroup</a>
  -    directive in <a
  -    href="mod/core.html#virtualhost">VirtualHost</a> definitions.
  -    By setting this directive 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 this directive is not
  -    specified for a
  -    <code>&lt;VirtualHost&gt;</code> then the main server userid is
  -    assumed.</p>
  +    <p><strong>Virtual Hosts:</strong><br> One way to use the suEXEC
  +    wrapper is through the <a href="./mod/mod_suexec.html#suexecusergroup" class="directive"><code
class="directive">SuexecUserGroup</code></a> directive in
  +    <a href="./mod/core.html#virtualhost" class="directive"><code class="directive">VirtualHost</code></a>
definitions.  By
  +    setting this directive 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 <a href="./mod/core.html#virtualhost"
class="directive"><code class="directive">&lt;VirtualHost&gt;</code></a>.
If this
  +    directive is not specified for a <a href="./mod/core.html#virtualhost" class="directive"><code
class="directive">&lt;VirtualHost&gt;</code></a> then the main server
userid
  +    is assumed.</p>
   
  -    <p><strong>User directories:</strong><br />
  +    <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>"
  @@ -544,31 +473,23 @@
       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>
  +<h2><a name="debug">Debugging suEXEC</a></h2>
   
  -    <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
  +    <p>The suEXEC wrapper will write log information
       to the file defined with the --with-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>
  +<h2><a name="jabberwock">Beware the Jabberwock:
  +    Warnings &amp; Examples</a></h2>
   
  -    <p align="left"><strong>NOTE!</strong> This section may not be
  +    <p><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, see the Apache Group's <a href="http://www.apache.org/docs-2.0/suexec.html">Online
       Documentation</a> version.</p>
   
  -    <p align="left">There are a few points of interest regarding
  +    <p>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>
   
  @@ -613,9 +534,4 @@
         </li>
       </ul>
   
  -    <p align="center"><strong><a href="suexec.html">BACK TO
  -    CONTENTS</a></strong></p>
  -    <!--#include virtual="footer.html" -->
  -  </body>
  -</html>
  -
  +<hr></blockquote><h3 align="center">Apache HTTP Server Version 2.0</h3><a
href="./"><img src="./images/index.gif" alt="Index"></a><a href="./"><img
src="./images/home.gif" alt="Home"></a></body></html>
  \ No newline at end of file
  
  
  
  1.1                  httpd-2.0/docs/manual/suexec.xml
  
  Index: suexec.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8" ?>
  <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
  <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
  
  <manualpage>
    <relativepath href="."/>
  
    <title>suEXEC Support</title>
  
    <summary>
      <p>The <strong>suEXEC</strong> feature 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>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>
    </summary>
  
  <section id="before"><title>Before we begin</title>
  
      <p>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>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>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>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>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>Still with us? Yes? Good. Let's move on!</p>
  </section>
  
  <section id="model"><title>suEXEC Security Model</title>
  
      <p>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><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>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>
  
      <p>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>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>
  </section>
  
  <section id="install"><title>Configuring &amp; Installing
      suEXEC</title>
  
      <p>Here's where we begin the fun.</p>
  
      <p><strong>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
        --with-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>--with-suexec-bin=<em>PATH</em></code></dt>
  
        <dd>The path to the suexec binary must be hard-coded in
        the server for security reasons. Use this option to override
        the default path. <em>e.g.</em>
        <code>--with-suexec-bin=/usr/sbin/suexec</code></dd>
  
        <dt><code>--with-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>--with-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>--with-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>--with-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>--with-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>--with-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>--with-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>
  
      <p><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>
  
  <example>
      suEXEC setup:<br />
              suexec binary: /usr/local/apache/sbin/suexec<br />
              document root: /usr/local/apache/share/htdocs<br />
             userdir suffix: public_html<br />
                    logfile: /usr/local/apache/var/log/suexec_log<br />
                  safe path: /usr/local/bin:/usr/bin:/bin<br />
                  caller ID: www<br />
            minimum user ID: 100<br />
           minimum group ID: 100<br />
  </example>
  
      <p><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>
  
  </section>
  
  <section id="enable"><title>Enabling &amp; Disabling
      suEXEC</title>
  
      <p>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>
  <example>
      [notice] suEXEC mechanism enabled (wrapper: <em>/path/to/suexec</em>)
  </example>
      <p>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>.</p>
  
       <p>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. </p>
       <p>If you want to disable suEXEC you should kill and restart
      Apache after you have removed the "suexec" file. </p>
  </section>
  
  <section id="usage"><title>Using suEXEC</title>
  
      <p><strong>Virtual Hosts:</strong><br /> One way to use the
suEXEC
      wrapper is through the <directive
      module="mod_suexec">SuexecUserGroup</directive> directive in
      <directive module="core">VirtualHost</directive> definitions.  By
      setting this directive 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 <directive
      module="core" type="section">VirtualHost</directive>. If this
      directive is not specified for a <directive module="core"
      type="section">VirtualHost</directive> 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>
  </section>
  
  <section id="debug"><title>Debugging suEXEC</title>
  
      <p>The suEXEC wrapper will write log information
      to the file defined with the --with-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>
  
  </section>
  
  <section id="jabberwock"><title>Beware the Jabberwock:
      Warnings &amp; Examples</title>
  
      <p><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-2.0/suexec.html">Online
      Documentation</a> version.</p>
  
      <p>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>
  
  </section>
  
  </manualpage>
  
  

Mime
View raw message