home *** CD-ROM | disk | FTP | other *** search
- <?xml version="1.0" encoding="ISO-8859-1"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
- <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- This file is generated from xml source: DO NOT EDIT
- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- -->
- <title>suEXEC Support - Apache HTTP Server</title>
- <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
- <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
- <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
- <link href="./images/favicon.ico" rel="shortcut icon" /></head>
- <body id="manual-page"><div id="page-header">
- <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
- <p class="apache">Apache HTTP Server Version 2.0</p>
- <img alt="" src="./images/feather.gif" /></div>
- <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
- <div id="path">
- <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="./">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>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>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>
- </div>
- <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#before">Before we begin</a></li>
- <li><img alt="" src="./images/down.gif" /> <a href="#model">suEXEC Security Model</a></li>
- <li><img alt="" src="./images/down.gif" /> <a href="#install">Configuring & Installing
- suEXEC</a></li>
- <li><img alt="" src="./images/down.gif" /> <a href="#enable">Enabling & Disabling
- suEXEC</a></li>
- <li><img alt="" src="./images/down.gif" /> <a href="#usage">Using suEXEC</a></li>
- <li><img alt="" src="./images/down.gif" /> <a href="#debug">Debugging suEXEC</a></li>
- <li><img alt="" src="./images/down.gif" /> <a href="#jabberwock">Beware the Jabberwock:
- Warnings & Examples</a></li>
- </ul></div>
- <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
- <div class="section">
- <h2><a name="before" id="before">Before we begin</a></h2>
-
- <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>
- </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
- <div class="section">
- <h2><a name="model" id="model">suEXEC Security Model</a></h2>
-
- <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>
-
- <p class="indent">
- 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.
- </p>
- </li>
-
- <li>
- <strong>Is the user executing this wrapper a valid user of
- this system?</strong>
-
- <p class="indent">
- This is to ensure that the user executing the wrapper is
- truly a user of the system.
- </p>
- </li>
-
- <li>
- <strong>Is this valid user allowed to run the
- wrapper?</strong>
-
- <p class="indent">
- Is this user the user allowed to run this wrapper? Only
- one user (the Apache user) is allowed to execute this
- program.
- </p>
- </li>
-
- <li>
- <strong>Does the target program have an unsafe hierarchical
- reference?</strong>
-
- <p class="indent">
- Does the target program contain a leading '/' or have a
- '..' backreference? These are not allowed; the target
- program must reside within the Apache webspace.
- </p>
- </li>
-
- <li>
- <strong>Is the target user name valid?</strong>
-
- <p class="indent">
- Does the target user exist?
- </p>
- </li>
-
- <li>
- <strong>Is the target group name valid?</strong>
-
- <p class="indent">
- Does the target group exist?
- </p>
- </li>
-
- <li>
- <strong>Is the target user <em>NOT</em> superuser?</strong>
-
-
- <p class="indent">
- Presently, suEXEC does not allow 'root' to execute
- CGI/SSI programs.
- </p>
- </li>
-
- <li>
- <strong>Is the target userid <em>ABOVE</em> the minimum ID
- number?</strong>
-
- <p class="indent">
- 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.
- </p>
- </li>
-
- <li>
- <strong>Is the target group <em>NOT</em> the superuser
- group?</strong>
-
- <p class="indent">
- Presently, suEXEC does not allow the 'root' group to
- execute CGI/SSI programs.
- </p>
- </li>
-
- <li>
- <strong>Is the target groupid <em>ABOVE</em> the minimum ID
- number?</strong>
-
- <p class="indent">
- 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.
- </p>
- </li>
-
- <li>
- <strong>Can the wrapper successfully become the target user
- and group?</strong>
-
- <p class="indent">
- 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.
- </p>
- </li>
-
- <li>
- <strong>Does the directory in which the program resides
- exist?</strong>
-
- <p class="indent">
- If it doesn't exist, it can't very well contain files.
- </p>
- </li>
-
- <li>
- <strong>Is the directory within the Apache
- webspace?</strong>
-
- <p class="indent">
- 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?
- </p>
- </li>
-
- <li>
- <strong>Is the directory <em>NOT</em> writable by anyone
- else?</strong>
-
- <p class="indent">
- We don't want to open up the directory to others; only
- the owner user may be able to alter this directories
- contents.
- </p>
- </li>
-
- <li>
- <strong>Does the target program exist?</strong>
-
- <p class="indent">
- If it doesn't exists, it can't very well be executed.
- </p>
- </li>
-
- <li>
- <strong>Is the target program <em>NOT</em> writable by
- anyone else?</strong>
-
- <p class="indent">
- We don't want to give anyone other than the owner the
- ability to change the program.
- </p>
- </li>
-
- <li>
- <strong>Is the target program <em>NOT</em> setuid or
- setgid?</strong>
-
- <p class="indent">
- We do not want to execute programs that will then change
- our UID/GID again.
- </p>
- </li>
-
- <li>
- <strong>Is the target user/group the same as the program's
- user/group?</strong>
-
- <p class="indent">
- Is the user the owner of the file?
- </p>
- </li>
-
- <li>
- <strong>Can we successfully clean the process environment
- to ensure safe operations?</strong>
-
- <p class="indent">
- 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).
- </p>
- </li>
-
- <li>
- <strong>Can we successfully become the target program and
- execute?</strong>
-
- <p class="indent">
- Here is where suEXEC ends and the target program begins.
- </p>
- </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>
- </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
- <div class="section">
- <h2><a name="install" id="install">Configuring & Installing
- suEXEC</a></h2>
-
- <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>
-
- <div class="example"><p><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></p></div>
-
- <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>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
- <div class="section">
- <h2><a name="enable" id="enable">Enabling & Disabling
- suEXEC</a></h2>
-
- <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>
- <div class="example"><p><code>
- [notice] suEXEC mechanism enabled (wrapper: <em>/path/to/suexec</em>)
- </code></p></div>
- <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>
- </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
- <div class="section">
- <h2><a name="usage" id="usage">Using suEXEC</a></h2>
-
- <p><strong>Virtual Hosts:</strong><br /> One way to use the suEXEC
- wrapper is through the <code class="directive"><a href="./mod/mod_suexec.html#suexecusergroup">SuexecUserGroup</a></code> directive in
- <code class="directive"><a href="./mod/core.html#virtualhost">VirtualHost</a></code> 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 class="directive"><a href="./mod/core.html#virtualhost"><VirtualHost></a></code>. If this
- directive is not specified for a <code class="directive"><a href="./mod/core.html#virtualhost"><VirtualHost></a></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>
- </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
- <div class="section">
- <h2><a name="debug" id="debug">Debugging suEXEC</a></h2>
-
- <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>
-
- </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
- <div class="section">
- <h2><a name="jabberwock" id="jabberwock">Beware the Jabberwock:
- Warnings & Examples</a></h2>
-
- <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://httpd.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
-
- <p class="indent">
- 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.)
- </p>
- </li>
-
- <li>
- suEXEC's PATH environment variable
-
- <p class="indent">
- 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.
- </p>
- </li>
-
- <li>
- Altering the suEXEC code
-
- <p class="indent">
- 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.
- </p>
- </li>
- </ul>
-
- </div></div>
- <div id="footer">
- <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
- <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
- </body></html>