suexec.html.en revision 35f745d0d98970c673c5ef89cd48bbd2beeb2efe
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<html><head>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<title>Apache SetUserID Support</title>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder</head><body>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<!--#include virtual="header.html" -->
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<h1>Apache suEXEC Support</h1>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<hr>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<h3>What is suEXEC?</h3>
accab0bf9b8aa690d70174f41fe94370323959b9Christian MaederThe <b>suEXEC</b> feature, introduced in Apache 1.2 provides the ability to
1012fdd997ea1f35eee2ccdd4015199f09f18fe9Christian Maederrun <b>CGI</b> programs under user ids different from the user id of the
59316321b20af89de1c2d4cd53183e04b72662c4Christian Maedercalling web-server. Used properly, this feature can reduce considerably the
59316321b20af89de1c2d4cd53183e04b72662c4Christian Maederinsecurity of allowing users to run CGI programs. At the same time, improperly
59316321b20af89de1c2d4cd53183e04b72662c4Christian Maederconfigured, this facility can crash your computer, burn your house down and
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maedersteal all the money from your retirement fund. <b>:-)</b> If you aren't
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maederfamiliar with managing setuid root programs and the security issues they
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maederpresent, we highly recommend that you not consider using this feature.<p>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<hr>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<h3>Enabling suEXEC Support</h3>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian MaederHaving said all that, enabling this feature is purposefully difficult with
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maederthe intent that it will only be installed by users determined to use it and
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maederis not part of the normal install/compile process.<p>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<h3>Configuring the suEXEC wrapper</h3>
d73d522b2ffe201e6233b576be9c0fb0ddbf6313Christian MaederFrom the top-level of the Apache source tree, type:&nbsp;&nbsp;<b><code>cd support [ENTER]</code></b><p>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian MaederEdit the <code>suexec.h</code> file and change the following macros to match your
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maederlocal Apache installation.<p>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<i>From support/suexec.h</i>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<code>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder<pre>
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder/*
59316321b20af89de1c2d4cd53183e04b72662c4Christian Maeder * HTTPD_USER -- Define as the username under which Apache normally
ec676ed8bdc0f0a1d52793db1d75eb0c8d6f0f05Christian Maeder * runs. This is the only user allowed to execute
d73d522b2ffe201e6233b576be9c0fb0ddbf6313Christian Maeder * this program.
d73d522b2ffe201e6233b576be9c0fb0ddbf6313Christian Maeder */
4654dbb45f8a4aea7aa5fed6be22c9efff19bfcaChristian Maeder#define HTTPD_USER "www"
accab0bf9b8aa690d70174f41fe94370323959b9Christian Maeder
accab0bf9b8aa690d70174f41fe94370323959b9Christian Maeder/*
accab0bf9b8aa690d70174f41fe94370323959b9Christian Maeder * LOG_EXEC -- Define this as a filename if you want all suEXEC
accab0bf9b8aa690d70174f41fe94370323959b9Christian Maeder * transactions and errors logged for auditing and
accab0bf9b8aa690d70174f41fe94370323959b9Christian Maeder * debugging purposes.
62198789c7cb57cac13399055515921c0fe3483fChristian Maeder */
#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
/*
* 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.
*/
#define DOC_ROOT "/usr/local/etc/httpd/htdocs"
/*
* SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
*
*/
#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
</pre>
</code>
<h3>Compiling the suEXEC wrapper</h3>
At the shell command prompt, type:&nbsp;&nbsp;<b><code>cc suexec.c -o suexec [ENTER]</code></b>.<p>
This should create the <b><em>suexec</em></b> 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>
<i>From src/httpd.h</i>
<code>
<pre>
/* The path to the suEXEC wrapper */
#ifndef SUEXEC_BIN
#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
#endif
</pre>
</code>
<p>
If your installation requires location of the wrapper program in a different
directory, edit src/httpd.h and recompile your Apache server. See <a href="install.html">Compiling and Installing Apache</a> for more info on this process.<p>
<h3>Installing the suEXEC wrapper</h3>
Copy the <b><em>suexec</em></b> executable created in the exercise above to the defined
location for <b>SUEXEC_BIN</b>.<p>
In order for the wrapper to set the user id for execution requests it must me installed
as owner <b><em>root</em></b> and must have the setuserid execution bit set for file modes.
If you are not running a <b><em>root</em></b> user shell, do so now and execute the following
commands.<p>
<b><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p>
<b><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p>
<i>Change the path to the suEXEC wrapper to match your system installation.</i>
<hr>
<h3><a name="model">Security Model of suEXEC</a></h3>
The <b>suEXEC</b> 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 <b>must be a valid user on this system</b>.
<li>User executing the wrapper <b>must be the compiled in HTTPD_USER</b>.
<li>The command that the request wishes to execute <b>must not contain a /</b>.
<li>The command being executed <b>must reside under the compiled in DOC_ROOT</b>.
<li>The current working directory <b>must be a directory</b>.
<li>The current working directory <b>must not be writable by <em>group</em> or <em>other</em></b>.
<li>The command being executed <b>cannot be a symbolic link</b>.
<li>The command being executed <b>cannot be writable by <em>group</em> or <em>other</em></b>.
<li>The command being executed <b>cannot be a <em>setuid</em> or <em>setgid</em> program</b>.
<li>The target UID and GID <b>must be a valid user and group on this system</b>.
<li>The target UID and GID to execute as, <b>must match the UID and GID of the directory</b>.
<li>The target execution UID and GID <b>must not be the privileged ID 0</b>.
</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. <b>:-)</b>
<hr>
<h3>Using suEXEC</h3>
After properly installing the <b>suexec</b> wrapper executable, you must kill and restart
the Apache server. A simple <code><b>kill -1 `cat httpd.pid`</b></code> will not be enough.
Upon startup of the web-server, if Apache finds a properly configured <b>suexec</b> 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 <b><em>setuid root</em></b>. Check your installation and try again.<p>
One way to use <b>suEXEC</b> is through the <a href="mod/core.html#user"><b>User</b></a> and <a href="mod/core.html#group"><b>Group</b></a> directives in <a href="mod/core.html#virtualhost"><b>VirtualHost</b></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 <b>User</b> and <b>Group</b> defined for that <b>&lt;VirtualHost&gt;</b>. If only one or
neither of these directives are specified for a <b>&lt;VirtualHost&gt;</b> then the main
server userid is assumed.<p>
<b>suEXEC</b> 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 <b>~</b> 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 the <code>suexec.h</code> 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.
<!--#include virtual="footer.html" -->
</BODY>
</HTML>