First of cut of suexec docs

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@77125 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 139 insertions, 3 deletions

diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html
index c1207ac01a..5c0ebef684 100644
--- a/docs/manual/suexec.html
+++ b/docs/manual/suexec.html
@@ -7,14 +7,150 @@
 
 <hr>
 
-<h2>What is SUExec?</h2>
+<h2>What is suEXEC?</h2>
+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 webserver. 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 
+familar with managing setuid root programs and the security issues they
+present, we highly recommend that you not consider using this feature.<p>
 
-<h2>Enabling SUExec Support</h2>
+<h2>Enabling suEXEC Support</h2>
+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>
 
-<h2>When SUExec Is Used</h2>
+<ul>
+<h3>Configuring the suEXEC wrapper</h3>
+From the toplevel of the Apache source tree, type:&nbsp;&nbsp;<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 DocuemntRoot set for Apache.  This
+ *             will be the only hierarchy (aside from UserDirs)
+ *             that can be used for suEXEC behaviour.
+ */
+#define DOC_ROOT "/usr/local/etc/httpd/htdocs"
+
+/*
+ * NNAME -- Define this as the name for the nobody account
+ *          on your operating system.  Most systems will just
+ *          need the default 'nobody'.
+ */
+#define NNAME "nobody"
+
+/* NGID -- Define this as the *number* for the nogroup group
+ *         on your operating system.  Most systems will have
+ *         a -1 or -2.  Others might have something above
+ *         65000.
+ */
+#define NGID -1
+</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>
+</ul>
+
+<a name="model"></a>
+<h2>Security Model of suEXEC</h2>
+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 writeable 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>.
+<li>Group access list is set to NOGROUP and the command is executed.
+</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>
+
+<h2>Using suEXEC</h2>
+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 webserver, 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.
+
+<h2>Debugging suEXEC</h2>
+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>