randy 96/12/01 12:04:02
Modified: htdocs/manual suexec.html
Log:
First of cut of suexec docs
Revision Changes Path
1.2 +139 -3 apache/htdocs/manual/suexec.html
Index: suexec.html
===================================================================
RCS file: /export/home/cvs/apache/htdocs/manual/suexec.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -C3 -r1.1 -r1.2
*** suexec.html 1996/12/01 17:06:57 1.1
--- suexec.html 1996/12/01 20:04:00 1.2
***************
*** 7,20 ****
<hr>
! <h2>What is SUExec?</h2>
! <h2>Enabling SUExec Support</h2>
! <h2>When SUExec Is Used</h2>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
--- 7,156 ----
<hr>
! <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>
! 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 toplevel 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 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: <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><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.
+
+ <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>
