mirror of
https://github.com/apache/httpd.git
synced 2025-10-25 21:57:48 +03:00
320c229e8b
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91461 13f79535-47bb-0310-9956-ffa450edef68
621 lines
22 KiB
HTML
621 lines
22 KiB
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>
|
|
|