Mailing List Archive: cvs commit: apache/htdocs/manual suexec.html

randy 97/06/05 13:07:21

Modified: htdocs/manual suexec.html
Log:
Update suexec docs.
Reviewed by: Ken Coar, Randy Terbush
Submitted by: Jason Dour

Revision Changes Path
1.11 +447 -132 apache/htdocs/manual/suexec.html

Index: suexec.html
===================================================================
RCS file: /export/home/cvs/apache/htdocs/manual/suexec.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C3 -r1.10 -r1.11
*** suexec.html 1997/06/04 11:07:51 1.10
--- suexec.html 1997/06/05 20:07:19 1.11
***************
*** 1,8 ****
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
! <html><head>
! <title>Apache SetUserID Support</title>
! </head>
!

<BODY
BGCOLOR="#FFFFFF"
--- 1,8 ----
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
! <HTML>
! <HEAD>
! <TITLE>Apache suEXEC Support</TITLE>
! </HEAD>

<BODY
BGCOLOR="#FFFFFF"
***************
*** 12,161 ****
ALINK="#FF0000"
>

- <h1 ALIGN="CENTER">Apache suEXEC Support</h1>

! <hr>

! <h3>What is suEXEC?</h3>
! The suEXEC feature, introduced in Apache 1.2 provides
! the ability to run CGI 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. :-) 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.
!
! <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.
!
! <h3>Configuring the suEXEC wrapper</h3>
! From the top-level of the Apache source tree,
! type:  <code>cd support [ENTER]</code>
Edit the <code>suexec.h</code> file and change the following macros to
! match your local Apache installation.
From support/suexec.h
! <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>
!
! <h3>Compiling the suEXEC wrapper</h3>
! At the shell command prompt, type:  <code>cc suexec.c
! -o suexec [ENTER]</code>.
This should create the suexec wrapper executable.

! <h3>Compiling Apache for suEXEC support</h3>
By default, Apache is compiled to look for the suEXEC wrapper in the following
! location.
From src/httpd.h
! <pre>
! /* The path to the suEXEC wrapper */
! #ifndef SUEXEC_BIN
! #define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
! #endif
! </pre>
! 
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.

! <h3>Installing the suEXEC wrapper</h3>
Copy the suexec executable created in the
! exercise above to the defined location for SUEXEC_BIN.
! In order for the wrapper to set the user ID for execution requests it
! must me installed as owner root and must have
! the setuserid execution bit set for file modes.
! If you are not running a root user shell, do
! so now and execute the following commands.
!
! <code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code>
! <code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code>
!
! Change the path to the suEXEC wrapper to match your system
! installation.
!
! <hr>
!
! <h3><a name="model">Security Model of suEXEC</a></h3>
! The suEXEC 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 must be a valid user on this
! system.
! <li>User executing the wrapper must be the compiled in
! HTTPD_USER.
! <li>The command that the request wishes to execute must not
! contain a leading / or ../, or the string "/../" anywhere.
! <li>The command being executed must reside under the compiled in
! DOC_ROOT.
! <li>The current working directory must be a directory.
! <li>The current working directory must not be writable by
! group or other.
! <li>The command being executed cannot be a symbolic link.
! <li>The command being executed cannot be writable by
! group or other.
! <li>The command being executed cannot be a setuid or
! setgid program.
! <li>The target UID and GID must be a valid user and group on
! this system.
! <li>The target UID and GID to execute as, must match the UID and
! GID of the directory.
! <li>The target execution UID and GID must not be the privileged
! ID 0.
! </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. :-)

! <hr>

! <h3>Using suEXEC</h3>
After properly installing the suexec wrapper
! executable, you must kill and restart the Apache server. A simple
! <code>kill -1 `cat httpd.pid`</code> will not be enough.
Upon startup of the web-server, if Apache finds a properly configured
suexec wrapper, it will print the following message to
! the console:

! <code>Configuring Apache for use with suexec wrapper.</code>

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 setuid root. Check
! your installation and try again.

One way to use suEXEC is through the
<a href="mod/core.html#user">User</a> and
<a href="mod/core.html#group">Group</a> directives in
--- 12,423 ----
ALINK="#FF0000"
>


! <H1 ALIGN="CENTER">Apache suEXEC Support</H1>
!
! 
! <OL>
! <LH><BIG>CONTENTS</BIG></LH>
! <LI><A HREF="#what">What is suEXEC?</A></LI>
! <LI><A HREF="#before">Before we begin.</A></LI>
! <LI><A HREF="#model">suEXEC Security Model.</A></LI>
! <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI>
! <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI>
! <LI><A HREF="#debug">Debugging suEXEC</A></LI>
! <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings & Examples</A></LI>
! </OL>
! 
!
! <H3><A NAME="what">What is suEXEC?</A></H3>
! 
! The suEXEC feature -- introduced in Apache 1.2 -- provides
! Apache users the ability to run CGI and SSI
! programs under user IDs different from the user ID of the calling web-server.
! Normally, when a CGI or SSI program executes, it runs as the same user who is
! running the web server.
! 
!
! 
! Used properly, this feature can reduce considerably the security risks involved
! with allowing users to develop and run private CGI or SSI programs. However,
! if suEXEC is improperly configured, it can cause any number of problems and
! possibly create new holes in your computer's security. If you aren't familiar
! with managing setuid root programs and the security issues they present, we
! highly recommend that you not consider using suEXEC.
! 
!
! 
! <A HREF="suexec.html">BACK TO CONTENTS</A>
! 
!
! <H3><A NAME="before">Before we begin.</A></H3>
! 
! Before jumping head-first into this document, you should be aware of the
! assumptions made on the part of the Apache Group and this document.
! 
!
! 
! First, it is assumed that you are using a UNIX derivate operating system that
! is capable of setuid and setgid operations.
! All command examples are given in this regard. Other platforms, if they are
! capable of supporting suEXEC, may differ in their configuration.
! 
!
! 
! Second, it is assumed you are familiar with some basic concepts of your
! computer's security and its administration. This involves an understanding
! of setuid/setgid operations and the various effects they
! may have on your system and its level of security.
! 
!
! 
! Third, it is assumed that you are using an unmodified
! version of suEXEC code. All code for suEXEC has been carefully scrutinized and
! tested by the developers as well as numerous beta testers. Every precaution has
! been taken to ensure a simple yet solidly safe base of code. Altering this
! code can cause unexpected problems and new security risks. It is
! highly recommended you not alter the suEXEC code unless you
! are well versed in the particulars of security programming and are willing to
! share your work with the Apache Group for consideration.
! 
!
! 
! Fourth, and last, it has been the decision of the Apache Group to
! NOT make suEXEC part of the default installation of Apache.
! To this end, suEXEC configuration is a manual process requiring of the
! administrator careful attention to details. It is through this process
! that the Apache Group hopes to limit suEXEC installation only to those
! who are determined to use it.
! 
!
! 
! Still with us? Yes? Good. Let's move on!
! 
!
! 
! <A HREF="suexec.html">BACK TO CONTENTS</A>
! 
!
! <H3><A NAME="model">suEXEC Security Model</A></H3>
! 
! Before we begin configuring and installing suEXEC, we will first discuss
! the security model you are about to implement. By doing so, you may
! better understand what exactly is going on inside suEXEC and what precautions
! are taken to ensure your system's security.
! 
!
! 
! suEXEC is based on a setuid "wrapper" program that is
! called by the main Apache web server. This wrapper is called when an HTTP
! request is made for a CGI or SSI program that the administrator has designated
! to run as a userid other than that of the main server. When such a request
! is made, Apache provides the suEXEC wrapper with the program's name and the
! user and group IDs under which the program is to execute.
! 
!
! 
! The wrapper then employs the following process to determine success or
! failure -- if any one of these conditions fail, the program logs the failure
! and exits with an error, otherwise it will continue:
! <OL>
! <LI>Was the wrapper called with the proper number of arguments?
! <BLOCKQUOTE>
! The wrapper will only execute if it is given the proper number of arguments.
! The proper argument format is known to the Apache web server. If the wrapper
! is not receiving the proper number of arguments, it is either being hacked, or
! there is something wrong with the suEXEC portion of your Apache binary.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the user executing this wrapper a valid user of this system?
! <BLOCKQUOTE>
! This is to ensure that the user executing the wrapper is truly a user of the system.
! </BLOCKQUOTE>
! </LI>
! <LI>Is this valid user allowed to run the wrapper?
! <BLOCKQUOTE>
! Is this user the user allowed to run this wrapper? Only one user (the Apache
! user) is allowed to execute this program.
! </BLOCKQUOTE>
! </LI>
! <LI>Does the target program have an unsafe hierarchical reference?
! <BLOCKQUOTE>
! Does the target program contain a leading '/' or have a '..' backreference? These
! are not allowed; the target program must reside within the Apache webspace.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target user name valid?
! <BLOCKQUOTE>
! Does the target user exist?
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target group name valid?
! <BLOCKQUOTE>
! Does the target group exist?
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target user NOT superuser?
! <BLOCKQUOTE>
! Presently, suEXEC does not allow 'root' to execute CGI/SSI programs.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target userid ABOVE the minimum ID number?
! <BLOCKQUOTE>
! The minimum user ID number is specified during configuration. This allows you
! to set the lowest possible userid that will be allowed to execute CGI/SSI programs.
! This is useful to block out "system" accounts.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target group NOT the superuser group?
! <BLOCKQUOTE>
! Presently, suEXEC does not allow the 'root' group to execute CGI/SSI programs.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target groupid ABOVE the minimum ID number?
! <BLOCKQUOTE>
! The minimum group ID number is specified during configuration. This allows you
! to set the lowest possible groupid that will be allowed to execute CGI/SSI programs.
! This is useful to block out "system" groups.
! </BLOCKQUOTE>
! </LI>
! <LI>Can the wrapper successfully become the target user and group?
! <BLOCKQUOTE>
! Here is where the program becomes the target user and group via setuid and setgid
! calls. The group access list is also initialized with all of the groups of which
! the user is a member.
! </BLOCKQUOTE>
! </LI>
! <LI>Does the directory in which the program resides exist?
! <BLOCKQUOTE>
! If it doesn't exist, it can't very well contain files.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the directory within the Apache webspace?
! <BLOCKQUOTE>
! If the request is for a regular portion of the server, is the requested directory
! within the server's document root? If the request is for a UserDir, is the requested
! directory within the user's document root?
! </BLOCKQUOTE>
! </LI>
! <LI>Is the directory NOT writable by anyone else?
! <BLOCKQUOTE>
! We don't want to open up the directory to others; only the owner user may be able
! to alter this directories contents.
! </BLOCKQUOTE>
! </LI>
! <LI>Does the target program exist?
! <BLOCKQUOTE>
! If it doesn't exists, it can't very well be executed.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target program NOT writable by anyone else?
! <BLOCKQUOTE>
! We don't want to give anyone other than the owner the ability to change the program.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target program NOT setuid or setgid?
! <BLOCKQUOTE>
! We do not want to execute programs that will then change our UID/GID again.
! </BLOCKQUOTE>
! </LI>
! <LI>Is the target user/group the same as the program's user/group?
! <BLOCKQUOTE>
! Is the user the owner of the file?
! </BLOCKQUOTE>
! </LI>
! <LI>Can we successfully clean the process environment to ensure safe operations?
! <BLOCKQUOTE>
! suEXEC cleans the process' environment by establishing a safe execution PATH (defined
! during configuration), as well as only passing through those variables whose names
! are listed in the safe environment list (also created during configuration).
! </BLOCKQUOTE>
! </LI>
! <LI>Can we successfully become the target program and execute?
! <BLOCKQUOTE>
! Here is where suEXEC ends and the target program begins.
! </BLOCKQUOTE>
! </LI>
! </OL>
! 
!
! 
! This is the standard operation of the the suEXEC wrapper's security model.
! It is somewhat stringent and can impose new limitations and guidelines for
! CGI/SSI design, but it was developed carefully step-by-step with security
! in mind.
! 
!
! 
! For more information as to how this security model can limit your possibilities
! in regards to server configuration, as well as what security risks can be avoided
! with a proper suEXEC setup, see the <A HREF="#beware">"Beware the Jabberwock"</A>
! section of this document.
! 
!
! 
! <A HREF="suexec.html">BACK TO CONTENTS</A>
! 
!
! <H3><A NAME="install">Configuring & Installing suEXEC</A></H3>
! 
! Here's where we begin the fun. The configuration and installation of suEXEC is
! a four step process: edit the suEXEC header file, compile suEXEC, place the
! suEXEC binary in its proper location, and configure Apache for use with suEXEC.
! 
!
! 
! EDITING THE SUEXEC HEADER FILE 
! - From the top-level of the Apache source tree, type:  
! <code>cd support [ENTER]</code>
! 

! 
Edit the <code>suexec.h</code> file and change the following macros to
! match your local Apache installation.
! 
!
! 
From support/suexec.h
! <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"
!
! /*
! * UID_MIN -- Define this as the lowest UID allowed to be a target user
! * for suEXEC. For most systems, 500 or 100 is common.
! */
! #define UID_MIN 100
!
! /*
! * GID_MIN -- Define this as the lowest GID allowed to be a target group
! * for suEXEC. For most systems, 100 is common.
! */
! #define GID_MIN 100
!
! /*
! * USERDIR_SUFFIX -- Define to be the subdirectory under users'
! * home directories where suEXEC access should
! * be allowed. All executables under this directory
! * will be executable by suEXEC as the user so
! * they should be "safe" programs. If you are
! * using a "simple" UserDir directive (ie. one
! * without a "*" in it) this should be set to
! * the same value. suEXEC will not work properly
! * in cases where the UserDir directive points to
! * a location that is not the same as the user's
! * home directory as referenced in the passwd file.
! *
! * If you have VirtualHosts with a different
! * UserDir for each, you will need to define them to
! * all reside in one parent directory; then name that
! * parent directory here. IF THIS IS NOT DEFINED
! * PROPERLY, ~USERDIR CGI REQUESTS WILL NOT WORK!
! * See the suEXEC documentation for more detailed
! * information.
! */
! #define USERDIR_SUFFIX "public_html"
!
! /*
! * 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" /* Need me? */
!
! /*
! * 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>
! 
!
! 
! COMPILING THE SUEXEC WRAPPER 
! You now need to compile the suEXEC wrapper. At the shell command prompt,
! type:  <CODE>cc suexec.c -o suexec [ENTER]</CODE>.
This should create the suexec wrapper executable.
+ 

! 
! COMPILING APACHE FOR USE WITH SUEXEC 
By default, Apache is compiled to look for the suEXEC wrapper in the following
! location.
! 
!
! 
From src/httpd.h
! <PRE>
! /* The path to the suEXEC wrapper */
! #define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
! </PRE>
! 
!
! 
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.
! 

! 
! COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION 
Copy the suexec executable created in the
! exercise above to the defined location for SUEXEC_BIN.
! 

! 
! <CODE>cp suexec /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE>
! 
!
! 
! In order for the wrapper to set the user ID, it must me installed as owner
! root and must have the setuserid execution bit
! set for file modes. If you are not running a root
! user shell, do so now and execute the following commands.
! 
!
! 
! <CODE>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE> 
! <CODE>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE>
! 
!
! 
! <A HREF="suexec.html">BACK TO CONTENTS</A>
! 

! <H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3>
! 
After properly installing the suexec wrapper
! executable, you must kill and restart the Apache server. A simple
! <CODE>kill -1 `cat httpd.pid`</CODE> will not be enough.
Upon startup of the web-server, if Apache finds a properly configured
suexec wrapper, it will print the following message to
! the console:
! 

! 
! <CODE>Configuring Apache for use with suexec wrapper.</CODE>
! 

+ 
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 setuid root. Check
! your installation and try again.
! 

+ 
One way to use suEXEC is through the
<a href="mod/core.html#user">User</a> and
<a href="mod/core.html#group">Group</a> directives in
***************
*** 176,190 ****
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.
! 

</BODY>
</HTML>
--- 438,505 ----
execution to be enabled for the user and that the script must meet the
scrutiny of the <a href="#model">security checks</a> above.

! 
! <A HREF="suexec.html">BACK TO CONTENTS</A>
! 

! <H3><A NAME="debug">Debugging suEXEC</A></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.
! 
!
! 
! <A HREF="suexec.html">BACK TO CONTENTS</A>
! 
!
! <H3><A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A></H3>
! 
! NOTE! This section may not be complete. For the latest
! revision of this section of the documentation, see the Apache Group's
! <A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A>
! version.
! 
!
! 
! There are a few points of interest regarding the wrapper that can cause
! limitations on server setup. Please review these before submitting any
! "bugs" regarding suEXEC.
! <UL>
! <LH>suEXEC Points Of Interest</LH>
! <LI>Hierarchy limitations
! <BLOCKQUOTE>
! For security and efficiency reasons, all suexec requests must
! remain within either a top-level document root for virtual
! host requests, or one top-level personal document root for
! userdir requests. For example, if you have four VirtualHosts
! configured, you would need to structure all of your VHosts'
! document roots off of one main Apache document hierarchy to
! take advantage of suEXEC for VirtualHosts. (Example forthcoming.)
! </BLOCKQUOTE>
! </LI>
! <LI>suEXEC's PATH environment variable
! <BLOCKQUOTE>
! This can be a dangerous thing to change. Make certain every
! path you include in this define is a trusted
! directory. You don't want to open people up to having someone
! from across the world running a trojan horse on them.
! </BLOCKQUOTE>
! </LI>
! <LI>Altering the suEXEC code
! <BLOCKQUOTE>
! Again, this can cause Big Trouble if you try
! this without knowing what you are doing. Stay away from it
! if at all possible.
! </BLOCKQUOTE>
! </LI>
! </UL>
!
! 
! <A HREF="suexec.html">BACK TO CONTENTS</A>
! 

+ 
</BODY>
</HTML>