suexec.html revision e507b318e2b8f7f6a749b9fba35b1b65b560eacc
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>Apache SetUserID Support</title>
</head>
<BODY BGCOLOR="white" TEXT="black" LINK="blue" VLINK="navy" ALINK="red">
<!--#include virtual="header.html" -->
<h1 ALIGN="CENTER">Apache suEXEC Support</h1>
<hr>
<h3>What is suEXEC?</h3>
The <STRONG>suEXEC</STRONG> feature, introduced in Apache 1.2 provides
the ability to run <STRONG>CGI</STRONG> programs under user IDs
different from the user ID of the calling web-server. Used properly,
this feature can reduce considerably the insecurity of allowing users to
run CGI programs. At the same time, improperly configured, this facility
can crash your computer, burn your house down and steal all the money
from your retirement fund. <STRONG>:-)</STRONG> If you aren't familiar
with managing setuid root programs and the security issues they
present, we highly recommend that you not consider using this feature.<p>
<hr>
<h3>Enabling suEXEC Support</h3>
Having said all that, enabling this feature is purposefully difficult with
the intent that it will only be installed by users determined to use it and
<h3>Configuring the suEXEC wrapper</h3>
From the top-level of the Apache source tree,
type: <STRONG><code>cd support [ENTER]</code></STRONG><p>
match your local Apache installation.<p>
<pre>
/*
* HTTPD_USER -- Define as the username under which Apache normally
* runs. This is the only user allowed to execute
* this program.
*/
#define HTTPD_USER "www"
/*
* LOG_EXEC -- Define this as a filename if you want all suEXEC
* transactions and errors logged for auditing and
* debugging purposes.
*/
/*
* DOC_ROOT -- Define as the DocumentRoot set for Apache. This
* will be the only hierarchy (aside from UserDirs)
* that can be used for suEXEC behavior.
*/
/*
* SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
*
*/
</pre>
<h3>Compiling the suEXEC wrapper</h3>
-o suexec [ENTER]</code></STRONG>.<p>
This should create the <STRONG><em>suexec</em></STRONG> wrapper executable.
<h3>Compiling Apache for suEXEC support</h3>
By default, Apache is compiled to look for the suEXEC wrapper in the following
location.<p>
<pre>
/* The path to the suEXEC wrapper */
#ifndef SUEXEC_BIN
#endif
</pre>
<p>
If your installation requires location of the wrapper program in a different
info on this process.<p>
<h3>Installing the suEXEC wrapper</h3>
Copy the <STRONG><em>suexec</em></STRONG> executable created in the
exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.<p>
In order for the wrapper to set the user ID for execution requests it
must me installed as owner <STRONG><em>root</em></STRONG> and must have
the setuserid execution bit set for file modes.
If you are not running a <STRONG><em>root</em></STRONG> user shell, do
so now and execute the following commands.<p>
<EM>Change the path to the suEXEC wrapper to match your system
installation.</EM>
<hr>
<h3><a name="model">Security Model of suEXEC</a></h3>
The <STRONG>suEXEC</STRONG> wrapper supplied with Apache performs the
following security checks before it will execute any program passed to
it for execution.
<ol>
<li>User executing the wrapper <STRONG>must be a valid user on this
system</STRONG>.
<li>User executing the wrapper <STRONG>must be the compiled in
HTTPD_USER</STRONG>.
<li>The command that the request wishes to execute <STRONG>must not
contain a leading / or ../, or the string "/../" anywhere</STRONG>.
<li>The command being executed <STRONG>must reside under the compiled in
DOC_ROOT</STRONG>.
<li>The current working directory <STRONG>must be a directory</STRONG>.
<li>The current working directory <STRONG>must not be writable by
<em>group</em> or <em>other</em></STRONG>.
<li>The command being executed <STRONG>cannot be a symbolic link</STRONG>.
<li>The command being executed <STRONG>cannot be writable by
<em>group</em> or <em>other</em></STRONG>.
<li>The command being executed <STRONG>cannot be a <em>setuid</em> or
<em>setgid</em> program</STRONG>.
<li>The target UID and GID <STRONG>must be a valid user and group on
this system</STRONG>.
<li>The target UID and GID to execute as, <STRONG>must match the UID and
GID of the directory</STRONG>.
<li>The target execution UID and GID <STRONG>must not be the privileged
ID 0</STRONG>.
</ol>
If any of these issues are too restrictive, or do not seem restrictive
enough, you are welcome to install your own version of the wrapper.
We've given you the rope, now go have fun with it. <STRONG>:-)</STRONG>
<hr>
<h3>Using suEXEC</h3>
After properly installing the <STRONG>suexec</STRONG> wrapper
executable, you must kill and restart the Apache server. A simple
Upon startup of the web-server, if Apache finds a properly configured
<STRONG>suexec</STRONG> wrapper, it will print the following message to
the console:<p>
<code>Configuring Apache for use with suexec wrapper.</code><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 <STRONG><em>setuid root</em></STRONG>. Check
your installation and try again.<p>
One way to use <STRONG>suEXEC</STRONG> is through the
definitions. By setting these directives to values different from the
main server user ID, all requests for CGI resources will be executed as
the <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that
<STRONG><VirtualHost></STRONG>. If only one or
neither of these directives are specified for a
<STRONG><VirtualHost></STRONG> then the main
server userid is assumed.<p>
<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as
the user to which the request is being directed. This is accomplished by
using the <STRONG>~</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.
<hr>
<h3>Debugging suEXEC</h3>
The suEXEC wrapper will write log information to the location defined in
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.
<!--#include virtual="footer.html" -->
</BODY>
</HTML>