| <html><head> |
| <title>Apache SetUserID Support</title> |
| </head><body> |
| |
| <!--#include virtual="header.html" --> |
| <h1>Apache suEXEC Support</h1> |
| |
| <hr> |
| |
| <h3>What is suEXEC?</h3> |
| The <b>suEXEC</b> feature, introduced in Apache 1.2 provides the ability to |
| run <b>CGI</b> 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. <b>:-)</b> 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 |
| is not part of the normal install/compile process.<p> |
| |
| <ul> |
| <h3>Configuring the suEXEC wrapper</h3> |
| From the top-level of the Apache source tree, type: <b><code>cd support [ENTER]</code></b><p> |
| Edit the <code>suexec.h</code> file and change the following macros to match your |
| local Apache installation.<p> |
| <i>From support/suexec.h</i> |
| <code> |
| <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. |
| */ |
| #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: <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> |
| </ul> |
| |
| <hr> |
| |
| <a name="model"></a> |
| <h3>Security Model of suEXEC</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 privledged 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><VirtualHost></b>. If only one or |
| neither of these directives are specified for a <b><VirtualHost></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> |
| |
