suexec.html revision bf3d9f591e5af24fdcaa9029094dc045878d1d1a
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster BGCOLOR="#FFFFFF"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster TEXT="#000000"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster LINK="#0000FF"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster VLINK="#000080"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster ALINK="#FF0000"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<!--#include virtual="header.html" -->
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterThe <STRONG>suEXEC</STRONG> feature, introduced in Apache 1.2 provides
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthe ability to run <STRONG>CGI</STRONG> programs under user IDs
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterdifferent from the user ID of the calling web-server. Used properly,
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthis feature can reduce considerably the insecurity of allowing users to
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterrun CGI programs. At the same time, improperly configured, this facility
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fostercan crash your computer, burn your house down and steal all the money
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterfrom your retirement fund. <STRONG>:-)</STRONG> If you aren't familiar
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterwith managing setuid root programs and the security issues they
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterpresent, we highly recommend that you not consider using this feature.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterHaving said all that, enabling this feature is purposefully difficult with
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthe intent that it will only be installed by users determined to use it and
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosteris not part of the normal install/compile process.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterFrom the top-level of the Apache source tree,
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fostertype: <STRONG><code>cd support [ENTER]</code></STRONG><p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterEdit the <code>suexec.h</code> file and change the following macros to
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fostermatch your local Apache installation.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * HTTPD_USER -- Define as the username under which Apache normally
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * runs. This is the only user allowed to execute
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * this program.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster#define HTTPD_USER "www"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * LOG_EXEC -- Define this as a filename if you want all suEXEC
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * transactions and errors logged for auditing and
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * debugging purposes.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * will be the only hierarchy (aside from UserDirs)
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * that can be used for suEXEC behavior.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterAt the shell command prompt, type: <STRONG><code>cc suexec.c
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterThis should create the <STRONG><em>suexec</em></STRONG> wrapper executable.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterBy default, Apache is compiled to look for the suEXEC wrapper in the following
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster/* The path to the suEXEC wrapper */
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster#ifndef SUEXEC_BIN
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterIf your installation requires location of the wrapper program in a different
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterdirectory, edit src/httpd.h and recompile your Apache server.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterSee <a href="install.html">Compiling and Installing Apache</a> for more
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterinfo on this process.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterCopy the <STRONG><em>suexec</em></STRONG> executable created in the
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterexercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterIn order for the wrapper to set the user ID for execution requests it
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fostermust me installed as owner <STRONG><em>root</em></STRONG> and must have
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthe setuserid execution bit set for file modes.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterIf you are not running a <STRONG><em>root</em></STRONG> user shell, do
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterso now and execute the following commands.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<STRONG><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<STRONG><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<EM>Change the path to the suEXEC wrapper to match your system
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterinstallation.</EM>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<h3><a name="model">Security Model of suEXEC</a></h3>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterThe <STRONG>suEXEC</STRONG> wrapper supplied with Apache performs the
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterfollowing security checks before it will execute any program passed to
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterit for execution.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>User executing the wrapper <STRONG>must be a valid user on this
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster system</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>User executing the wrapper <STRONG>must be the compiled in
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster HTTPD_USER</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The command that the request wishes to execute <STRONG>must not
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster contain a leading / or ../, or the string "/../" anywhere</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The command being executed <STRONG>must reside under the compiled in
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster DOC_ROOT</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The current working directory <STRONG>must be a directory</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The current working directory <STRONG>must not be writable by
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The command being executed <STRONG>cannot be a symbolic link</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The command being executed <STRONG>cannot be writable by
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The command being executed <STRONG>cannot be a <em>setuid</em> or
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The target UID and GID <STRONG>must be a valid user and group on
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster this system</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The target UID and GID to execute as, <STRONG>must match the UID and
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster GID of the directory</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<li>The target execution UID and GID <STRONG>must not be the privileged
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster ID 0</STRONG>.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterIf any of these issues are too restrictive, or do not seem restrictive
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterenough, you are welcome to install your own version of the wrapper.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterWe've given you the rope, now go have fun with it. <STRONG>:-)</STRONG>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterAfter properly installing the <STRONG>suexec</STRONG> wrapper
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterexecutable, you must kill and restart the Apache server. A simple
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<code><STRONG>kill -1 `cat httpd.pid`</STRONG></code> will not be enough.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterUpon startup of the web-server, if Apache finds a properly configured
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<STRONG>suexec</STRONG> wrapper, it will print the following message to
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthe console:<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<code>Configuring Apache for use with suexec wrapper.</code><p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterIf you don't see this message at server startup, the server is most
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterlikely not finding the wrapper program where it expects it, or the
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterexecutable is not installed <STRONG><em>setuid root</em></STRONG>. Check
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosteryour installation and try again.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterOne way to use <STRONG>suEXEC</STRONG> is through the
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<a href="mod/core.html#user"><STRONG>User</STRONG></a> and
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<a href="mod/core.html#group"><STRONG>Group</STRONG></a> directives in
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<a href="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></a>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterdefinitions. By setting these directives to values different from the
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fostermain server user ID, all requests for CGI resources will be executed as
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthe <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<STRONG><VirtualHost></STRONG>. If only one or
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterneither of these directives are specified for a
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<STRONG><VirtualHost></STRONG> then the main
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterserver userid is assumed.<p>
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthe user to which the request is being directed. This is accomplished by
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterusing the <STRONG>~</STRONG> character prefixing the user ID for whom
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterexecution is desired.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterThe only requirement needed for this feature to work is for CGI
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterexecution to be enabled for the user and that the script must meet the
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterscrutiny of the <a href="#model">security checks</a> above.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan FosterThe suEXEC wrapper will write log information to the location defined in
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterthe <code>suexec.h</code> as indicated above. If you feel you have
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterconfigured and installed the wrapper properly,
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosterhave a look at this log and the error_log for the server to see where
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Fosteryou may have gone astray.
2d0a88b18a041738cfe635b45bd1db56af469c91Allan Foster<!--#include virtual="footer.html" -->