-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache suEXEC Support</TITLE>
-</HEAD>
-<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
-<!--#include virtual="header.html" -->
-
-<H1 ALIGN="CENTER">Apache suEXEC Support</H1>
-
-<P ALIGN="LEFT">
-<OL>
- <LI><BIG><STRONG>CONTENTS</STRONG></BIG></LI>
- <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>
-</P>
-
-<H3><A NAME="what">What is suEXEC?</A></H3>
-<P ALIGN="LEFT">
-The <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides
-Apache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG>
-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.
-</P>
-
-<P ALIGN="LEFT">
-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.
-</P>
-
-<P ALIGN="CENTER">
-<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
-</P>
-
-<H3><A NAME="before">Before we begin.</A></H3>
-<P ALIGN="LEFT">
-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.
-</P>
-
-<P ALIGN="LEFT">
-First, it is assumed that you are using a UNIX derivate operating system that
-is capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations.
-All command examples are given in this regard. Other platforms, if they are
-capable of supporting suEXEC, may differ in their configuration.
-</P>
-
-<P ALIGN="LEFT">
-Second, it is assumed you are familiar with some basic concepts of your
-computer's security and its administration. This involves an understanding
-of <STRONG>setuid/setgid</STRONG> operations and the various effects they
-may have on your system and its level of security.
-</P>
-
-<P ALIGN="LEFT">
-Third, it is assumed that you are using an <STRONG>unmodified</STRONG>
-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
-<STRONG>highly</STRONG> 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.
-</P>
-
-<P ALIGN="LEFT">
-Fourth, and last, it has been the decision of the Apache Group to
-<STRONG>NOT</STRONG> 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.
-</P>
-
-<P ALIGN="LEFT">
-Still with us? Yes? Good. Let's move on!
-</P>
-
-<P ALIGN="CENTER">
-<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
-</P>
-
-<H3><A NAME="model">suEXEC Security Model</A></H3>
-<P ALIGN="LEFT">
-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.
-</P>
-
-<P ALIGN="LEFT">
-<STRONG>suEXEC</STRONG> 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.
-</P>
-
-<P ALIGN="LEFT">
-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><STRONG>Was the wrapper called with the proper number of arguments?</STRONG>
- <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><STRONG>Is the user executing this wrapper a valid user of this system?</STRONG>
- <BLOCKQUOTE>
- This is to ensure that the user executing the wrapper is truly a user of the system.
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG>
- <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><STRONG>Does the target program have an unsafe hierarchical reference?</STRONG>
- <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><STRONG>Is the target user name valid?</STRONG>
- <BLOCKQUOTE>
- Does the target user exist?
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the target group name valid?</STRONG>
- <BLOCKQUOTE>
- Does the target group exist?
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG>
- <BLOCKQUOTE>
- Presently, suEXEC does not allow 'root' to execute CGI/SSI programs.
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID number?</STRONG>
- <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><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG>
- <BLOCKQUOTE>
- Presently, suEXEC does not allow the 'root' group to execute CGI/SSI programs.
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID number?</STRONG>
- <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><STRONG>Can the wrapper successfully become the target user and group?</STRONG>
- <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><STRONG>Does the directory in which the program resides exist?</STRONG>
- <BLOCKQUOTE>
- If it doesn't exist, it can't very well contain files.
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the directory within the Apache webspace?</STRONG>
- <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><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG>
- <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><STRONG>Does the target program exist?</STRONG>
- <BLOCKQUOTE>
- If it doesn't exists, it can't very well be executed.
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone else?</STRONG>
- <BLOCKQUOTE>
- We don't want to give anyone other than the owner the ability to change the program.
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG>
- <BLOCKQUOTE>
- We do not want to execute programs that will then change our UID/GID again.
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Is the target user/group the same as the program's user/group?</STRONG>
- <BLOCKQUOTE>
- Is the user the owner of the file?
- </BLOCKQUOTE>
- </LI>
- <LI><STRONG>Can we successfully clean the process environment to ensure safe operations?</STRONG>
- <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><STRONG>Can we successfully become the target program and execute?</STRONG>
- <BLOCKQUOTE>
- Here is where suEXEC ends and the target program begins.
- </BLOCKQUOTE>
- </LI>
- </OL>
-</P>
-
-<P ALIGN="LEFT">
-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.
-</P>
-
-<P ALIGN="LEFT">
-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.
-</P>
-
-<P ALIGN="CENTER">
-<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
-</P>
-
-<H3><A NAME="install">Configuring & Installing suEXEC</A></H3>
-<P ALIGN="LEFT">
-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.
-</P>
-
-<P ALIGN="LEFT">
-<STRONG>EDITING THE SUEXEC HEADER FILE</STRONG><BR>
-- From the top-level of the Apache source tree, type:
-<STRONG><CODE>cd support [ENTER]</CODE></STRONG>
-</P>
-
-<P ALIGN="LEFT">
-Edit the <CODE>suexec.h</CODE> file and change the following macros to
-match your local Apache installation.
-</P>
-
-<P ALIGN="LEFT">
-<EM>From support/suexec.h</EM>
-<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/apache/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/apache/htdocs"
-
- /*
- * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables.
- *
- */
- #define SAFE_PATH "/usr/local/bin:/usr/bin:/bin"
-</PRE>
-</P>
-
-<P ALIGN="LEFT">
-<STRONG>COMPILING THE SUEXEC WRAPPER</STRONG><BR>
-You now need to compile the suEXEC wrapper. At the shell command prompt,
-type: <STRONG><CODE>cc suexec.c -o suexec [ENTER]</CODE></STRONG>.
-This should create the <STRONG><EM>suexec</EM></STRONG> wrapper executable.
-</P>
-
-<P ALIGN="LEFT">
-<STRONG>COMPILING APACHE FOR USE WITH SUEXEC</STRONG><BR>
-By default, Apache is compiled to look for the suEXEC wrapper in the following
-location.
-</P>
-
-<P ALIGN="LEFT">
-<EM>From src/httpd.h</EM>
-<PRE>
- /* The path to the suEXEC wrapper */
- #define SUEXEC_BIN "/usr/local/apache/sbin/suexec"
-</PRE>
-</P>
-
-<P ALIGN="LEFT">
-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>
-
-<P ALIGN="LEFT">
-<STRONG>COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION</STRONG><BR>
-Copy the <STRONG><EM>suexec</EM></STRONG> executable created in the
-exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.
-</P>
-
-<P ALIGN="LEFT">
-<STRONG><CODE>cp suexec /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG>
-</P>
-
-<P ALIGN="LEFT">
-In order for the wrapper to set the user ID, it must me installed as owner
-<STRONG><EM>root</EM></STRONG> and must have the setuserid execution bit
-set for file modes. If you are not running a <STRONG><EM>root</EM></STRONG>
-user shell, do so now and execute the following commands.
-</P>
-
-<P ALIGN="LEFT">
-<STRONG><CODE>chown root /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG><BR>
-<STRONG><CODE>chmod 4711 /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG>
-</P>
-
-<P ALIGN="CENTER">
-<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
-</P>
-
-<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3>
-<P ALIGN="LEFT">
-After properly installing the <STRONG>suexec</STRONG> wrapper
-executable, you must kill and restart the Apache server. A simple
-<STRONG><CODE>kill -1 `cat httpd.pid`</CODE></STRONG> will not be enough.
-Upon startup of the web-server, if Apache finds a properly configured
-<STRONG>suexec</STRONG> wrapper, it will print the following message to
-the console:
-</P>
-
-<P ALIGN="LEFT">
-<CODE>Configuring Apache for use with suexec wrapper.</CODE>
-</P>
-
-<P ALIGN="LEFT">
-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 <STRONG><EM>setuid root</EM></STRONG>. Check
-your installation and try again.
-</P>
-
-<P ALIGN="LEFT">
-One way to use <STRONG>suEXEC</STRONG> is through the
-<A HREF="mod/core.html#user"><STRONG>User</STRONG></A> and
-<A HREF="mod/core.html#group"><STRONG>Group</STRONG></A> directives in
-<A HREF="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></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 <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that
-<STRONG><VirtualHost></STRONG>. If only one or
-neither of these directives are specified for a
-<STRONG><VirtualHost></STRONG> then the main
-server userid is assumed.<P>
-
-<STRONG>suEXEC</STRONG> 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 <STRONG>~</STRONG> 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.
-
-<P ALIGN="CENTER">
-<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
-</P>
-
-<H3><A NAME="debug">Debugging suEXEC</A></H3>
-<P ALIGN="LEFT">
-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.
-</P>
-
-<P ALIGN="CENTER">
-<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
-</P>
-
-<H3><A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A></H3>
-<P ALIGN="LEFT">
-<STRONG>NOTE!</STRONG> 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.
-</P>
-
-<P ALIGN="LEFT">
-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>
- <LI><STRONG>suEXEC Points Of Interest</STRONG></LI>
- <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 <STRONG>trusted</STRONG>
- 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 <STRONG>Big Trouble</STRONG> if you try
- this without knowing what you are doing. Stay away from it
- if at all possible.
- </BLOCKQUOTE>
- </LI>
-</UL>
-
-<P ALIGN="CENTER">
-<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG>
-</P>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ -->
+<title>suEXEC Support - Apache HTTP Server</title>
+<link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="./style/css/prettify.css" />
+<script src="./style/scripts/prettify.js" type="text/javascript">
+</script>
+
+<link href="./images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
+<p class="apache">Apache HTTP Server Version 2.5</p>
+<img alt="" src="./images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.5</a></div><div id="page-content"><div id="preamble"><h1>suEXEC Support</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="./en/suexec.html" title="English"> en </a> |
+<a href="./fr/suexec.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
+<a href="./ja/suexec.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
+<a href="./ko/suexec.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
+<a href="./tr/suexec.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
+</div>
+
+ <p>The <strong>suEXEC</strong> feature provides users of the Apache
+ HTTP Server the ability
+ to run <strong>CGI</strong> and <strong>SSI</strong> 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.</p>
+
+ <p>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 <em>setuid root</em> programs
+ and the security issues they present, we highly recommend that
+ you not consider using suEXEC.</p>
+ </div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#before">Before we begin</a></li>
+<li><img alt="" src="./images/down.gif" /> <a href="#model">suEXEC Security Model</a></li>
+<li><img alt="" src="./images/down.gif" /> <a href="#install">Configuring & Installing
+ suEXEC</a></li>
+<li><img alt="" src="./images/down.gif" /> <a href="#enable">Enabling & Disabling
+ suEXEC</a></li>
+<li><img alt="" src="./images/down.gif" /> <a href="#usage">Using suEXEC</a></li>
+<li><img alt="" src="./images/down.gif" /> <a href="#debug">Debugging suEXEC</a></li>
+<li><img alt="" src="./images/down.gif" /> <a href="#jabberwock">Beware the Jabberwock:
+ Warnings & Examples</a></li>
+</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="before" id="before">Before we begin</a></h2>
+
+ <p>Before jumping head-first into this document,
+ you should be aware that certain assumptions are made about you and
+ the environment in which you will be using suexec.</p>
+
+ <p>First, it is assumed that you are using a UNIX
+ derivative operating system that is capable of
+ <strong>setuid</strong> and <strong>setgid</strong> operations.
+ All command examples are given in this regard. Other platforms,
+ if they are capable of supporting suEXEC, may differ in their
+ configuration.</p>
+
+ <p>Second, it is assumed you are familiar with
+ some basic concepts of your computer's security and its
+ administration. This involves an understanding of
+ <strong>setuid/setgid</strong> operations and the various
+ effects they may have on your system and its level of
+ security.</p>
+
+ <p>Third, it is assumed that you are using an
+ <strong>unmodified</strong> 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 <strong>highly</strong> 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 HTTP Server development team for consideration.</p>
+
+ <p>Fourth, and last, it has been the decision of
+ the Apache HTTP Server development team to <strong>NOT</strong> make suEXEC part of
+ the default installation of Apache httpd. To this end, suEXEC
+ configuration requires of the administrator careful attention
+ to details. After due consideration has been given to the
+ various settings for suEXEC, the administrator may install
+ suEXEC through normal installation methods. The values for
+ these settings need to be carefully determined and specified by
+ the administrator to properly maintain system security during
+ the use of suEXEC functionality. It is through this detailed
+ process that we hope to limit suEXEC
+ installation only to those who are careful and determined
+ enough to use it.</p>
+
+ <p>Still with us? Yes? Good. Let's move on!</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="model" id="model">suEXEC Security Model</a></h2>
+
+ <p>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.</p>
+
+ <p><strong>suEXEC</strong> is based on a setuid
+ "wrapper" program that is called by the main Apache HTTP 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 httpd provides the suEXEC wrapper with the
+ program's name and the user and group IDs under which the
+ program is to execute.</p>
+
+ <p>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:</p>
+
+ <ol>
+ <li>
+ <strong>Is the user executing this wrapper a valid user of
+ this system?</strong>
+
+ <p class="indent">
+ This is to ensure that the user executing the wrapper is
+ truly a user of the system.
+ </p>
+ </li>
+
+ <li>
+ <strong>Was the wrapper called with the proper number of
+ arguments?</strong>
+
+ <p class="indent">
+ The wrapper will only execute if it is given the proper
+ number of arguments. The proper argument format is known
+ to the Apache HTTP 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 httpd binary.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is this valid user allowed to run the
+ wrapper?</strong>
+
+ <p class="indent">
+ Is this user the user allowed to run this wrapper? Only
+ one user (the Apache user) is allowed to execute this
+ program.
+ </p>
+ </li>
+
+ <li>
+ <strong>Does the target CGI or SSI program have an unsafe
+ hierarchical reference?</strong>
+
+ <p class="indent">
+ Does the target CGI or SSI program's path contain a leading
+ '/' or have a '..' backreference? These are not allowed; the
+ target CGI/SSI program must reside within suEXEC's document
+ root (see <code>--with-suexec-docroot=<em>DIR</em></code>
+ below).
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target user name valid?</strong>
+
+ <p class="indent">
+ Does the target user exist?
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target group name valid?</strong>
+
+ <p class="indent">
+ Does the target group exist?
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target user <em>NOT</em> superuser?</strong>
+
+
+ <p class="indent">
+ suEXEC does not allow <code><em>root</em></code>
+ to execute CGI/SSI programs.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target userid <em>ABOVE</em> the minimum ID
+ number?</strong>
+
+ <p class="indent">
+ 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.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target group <em>NOT</em> the superuser
+ group?</strong>
+
+ <p class="indent">
+ Presently, suEXEC does not allow the <code><em>root</em></code>
+ group to execute CGI/SSI programs.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target groupid <em>ABOVE</em> the minimum ID
+ number?</strong>
+
+ <p class="indent">
+ 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.
+ </p>
+ </li>
+
+ <li>
+ <strong>Can the wrapper successfully become the target user
+ and group?</strong>
+
+ <p class="indent">
+ 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.
+ </p>
+ </li>
+
+ <li>
+ <strong>Can we change directory to the one in which the target
+ CGI/SSI program resides?</strong>
+
+ <p class="indent">
+ If it doesn't exist, it can't very well contain files. If we
+ can't change directory to it, it might as well not exist.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the directory within the httpd webspace?</strong>
+
+ <p class="indent">
+ If the request is for a regular portion of the server, is
+ the requested directory within suEXEC's document root? If
+ the request is for a <code class="directive"><a href="./mod/mod_userdir.html#userdir">UserDir</a></code>, is the requested directory
+ within the directory configured as suEXEC's userdir (see
+ <a href="#install">suEXEC's configuration options</a>)?
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the directory <em>NOT</em> writable by anyone
+ else?</strong>
+
+ <p class="indent">
+ We don't want to open up the directory to others; only
+ the owner user may be able to alter this directories
+ contents.
+ </p>
+ </li>
+
+ <li>
+ <strong>Does the target CGI/SSI program exist?</strong>
+
+ <p class="indent">
+ If it doesn't exists, it can't very well be executed.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target CGI/SSI program <em>NOT</em> writable
+ by anyone else?</strong>
+
+ <p class="indent">
+ We don't want to give anyone other than the owner the
+ ability to change the CGI/SSI program.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target CGI/SSI program <em>NOT</em> setuid or
+ setgid?</strong>
+
+ <p class="indent">
+ We do not want to execute programs that will then change
+ our UID/GID again.
+ </p>
+ </li>
+
+ <li>
+ <strong>Is the target user/group the same as the program's
+ user/group?</strong>
+
+ <p class="indent">
+ Is the user the owner of the file?
+ </p>
+ </li>
+
+ <li>
+ <strong>Can we successfully clean the process environment
+ to ensure safe operations?</strong>
+
+ <p class="indent">
+ 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).
+ </p>
+ </li>
+
+ <li>
+ <strong>Can we successfully become the target CGI/SSI program
+ and execute?</strong>
+
+ <p class="indent">
+ Here is where suEXEC ends and the target CGI/SSI program begins.
+ </p>
+ </li>
+ </ol>
+
+ <p>This is the standard operation of 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.</p>
+
+ <p>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="#jabberwock">"Beware the Jabberwock"</a> section of this
+ document.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="install" id="install">Configuring & Installing
+ suEXEC</a></h2>
+
+ <p>Here's where we begin the fun.</p>
+
+ <p><strong>suEXEC configuration
+ options</strong><br />
+ </p>
+
+ <dl>
+ <dt><code>--enable-suexec</code></dt>
+
+ <dd>This option enables the suEXEC feature which is never
+ installed or activated by default. At least one
+ <code>--with-suexec-xxxxx</code> option has to be provided
+ together with the <code>--enable-suexec</code> option to let
+ APACI accept your request for using the suEXEC feature.</dd>
+
+ <dt><code>--with-suexec-bin=<em>PATH</em></code></dt>
+
+ <dd>The path to the <code>suexec</code> binary must be hard-coded
+ in the server for security reasons. Use this option to override
+ the default path. <em>e.g.</em>
+ <code>--with-suexec-bin=/usr/sbin/suexec</code></dd>
+
+ <dt><code>--with-suexec-caller=<em>UID</em></code></dt>
+
+ <dd>The <a href="mod/mpm_common.html#user">username</a> under which
+ httpd normally runs. This is the only user allowed to
+ execute the suEXEC wrapper.</dd>
+
+ <dt><code>--with-suexec-userdir=<em>DIR</em></code></dt>
+
+ <dd>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" <code class="directive"><a href="./mod/mod_userdir.html#userdir">UserDir</a></code>
+ directive (ie. one without a "*" in it) this should be set to the same
+ value. suEXEC will not work properly in cases where the <code class="directive"><a href="./mod/mod_userdir.html#userdir">UserDir</a></code> directive points to
+ a location that is not the same as the user's home directory
+ as referenced in the <code>passwd</code> file. Default value is
+ "<code>public_html</code>".<br />
+ If you have virtual hosts with a different <code class="directive"><a href="./mod/mod_userdir.html#userdir">UserDir</a></code> for each,
+ you will need to define them to all reside in one parent
+ directory; then name that parent directory here. <strong>If
+ this is not defined properly, "~userdir" cgi requests will
+ not work!</strong></dd>
+
+ <dt><code>--with-suexec-docroot=<em>DIR</em></code></dt>
+
+ <dd>Define as the DocumentRoot set for httpd. This will be
+ the only hierarchy (aside from <code class="directive"><a href="./mod/mod_userdir.html#userdir">UserDir</a></code>s) that can be used for suEXEC behavior. The
+ default directory is the <code>--datadir</code> value with the suffix
+ "<code>/htdocs</code>", <em>e.g.</em> if you configure with
+ "<code>--datadir=/home/apache</code>" the directory
+ "<code>/home/apache/htdocs</code>" is used as document root for the
+ suEXEC wrapper.</dd>
+
+ <dt><code>--with-suexec-uidmin=<em>UID</em></code></dt>
+
+ <dd>Define this as the lowest UID allowed to be a target user
+ for suEXEC. For most systems, 500 or 100 is common. Default
+ value is 100.</dd>
+
+ <dt><code>--with-suexec-gidmin=<em>GID</em></code></dt>
+
+ <dd>Define this as the lowest GID allowed to be a target
+ group for suEXEC. For most systems, 100 is common and
+ therefore used as default value.</dd>
+
+ <dt><code>--with-suexec-logfile=<em>FILE</em></code></dt>
+
+ <dd>This defines the filename to which all suEXEC
+ transactions and errors are logged (useful for auditing and
+ debugging purposes). By default the logfile is named
+ "<code>suexec_log</code>" and located in your standard logfile
+ directory (<code>--logfiledir</code>).</dd>
+
+ <dt><code>--with-suexec-safepath=<em>PATH</em></code></dt>
+
+ <dd>Define a safe PATH environment to pass to CGI
+ executables. Default value is
+ "<code>/usr/local/bin:/usr/bin:/bin</code>".</dd>
+ </dl>
+
+ <h3>Compiling and installing the suEXEC wrapper</h3>
+
+
+ <p>If you have enabled the suEXEC feature with the
+ <code>--enable-suexec</code> option the <code>suexec</code> binary
+ (together with httpd itself) is automatically built if you execute
+ the <code>make</code> command.</p>
+
+ <p>After all components have been built you can execute the
+ command <code>make install</code> to install them. The binary image
+ <code>suexec</code> is installed in the directory defined by the
+ <code>--sbindir</code> option. The default location is
+ "/usr/local/apache2/bin/suexec".</p>
+
+ <p>Please note that you need <strong><em>root
+ privileges</em></strong> for the installation step. In order
+ for the wrapper to set the user ID, it must be installed as
+ owner <code><em>root</em></code> and must have the setuserid
+ execution bit set for file modes.</p>
+
+
+ <h3>Setting paranoid permissions</h3>
+
+
+ <p>Although the suEXEC wrapper will check to ensure that its
+ caller is the correct user as specified with the
+ <code>--with-suexec-caller</code> <code class="program"><a href="./programs/configure.html">configure</a></code>
+ option, there is
+ always the possibility that a system or library call suEXEC uses
+ before this check may be exploitable on your system. To counter
+ this, and because it is best-practise in general, you should use
+ filesystem permissions to ensure that only the group httpd
+ runs as may execute suEXEC.</p>
+
+ <p>If for example, your web server is configured to run as:</p>
+
+ <pre class="prettyprint lang-config">
+User www
+Group webgroup
+ </pre>
+
+
+ <p>and <code class="program"><a href="./programs/suexec.html">suexec</a></code> is installed at
+ "/usr/local/apache2/bin/suexec", you should run:</p>
+
+ <div class="example"><p><code>
+ chgrp webgroup /usr/local/apache2/bin/suexec<br />
+ chmod 4750 /usr/local/apache2/bin/suexec<br />
+ </code></p></div>
+
+ <p>This will ensure that only the group httpd runs as can even
+ execute the suEXEC wrapper.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="enable" id="enable">Enabling & Disabling
+ suEXEC</a></h2>
+
+ <p>Upon startup of httpd, it looks for the file
+ <code class="program"><a href="./programs/suexec.html">suexec</a></code> in the directory defined by the
+ <code>--sbindir</code> option (default is
+ "/usr/local/apache/sbin/suexec"). If httpd finds a properly
+ configured suEXEC wrapper, it will print the following message
+ to the error log:</p>
+
+<div class="example"><p><code>
+ [notice] suEXEC mechanism enabled (wrapper: <var>/path/to/suexec</var>)
+</code></p></div>
+
+ <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 <em>setuid root</em>.</p>
+
+ <p>If you want to enable the suEXEC mechanism for the first time
+ and an Apache HTTP Server is already running you must kill and
+ restart httpd. Restarting it with a simple HUP or USR1 signal
+ will not be enough. </p>
+ <p>If you want to disable suEXEC you should kill and restart
+ httpd after you have removed the <code class="program"><a href="./programs/suexec.html">suexec</a></code> file.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="usage" id="usage">Using suEXEC</a></h2>
+
+ <p>Requests for CGI programs will call the suEXEC wrapper only if
+ they are for a virtual host containing a <code class="directive"><a href="./mod/mod_suexec.html#suexecusergroup">SuexecUserGroup</a></code> directive or if
+ they are processed by <code class="module"><a href="./mod/mod_userdir.html">mod_userdir</a></code>.</p>
+
+ <p><strong>Virtual Hosts:</strong><br /> One way to use the suEXEC
+ wrapper is through the <code class="directive"><a href="./mod/mod_suexec.html#suexecusergroup">SuexecUserGroup</a></code> directive in
+ <code class="directive"><a href="./mod/core.html#virtualhost">VirtualHost</a></code> definitions. By
+ setting this directive to values different from the main server
+ user ID, all requests for CGI resources will be executed as the
+ <em>User</em> and <em>Group</em> defined for that <code class="directive"><a href="./mod/core.html#virtualhost"><VirtualHost></a></code>. If this
+ directive is not specified for a <code class="directive"><a href="./mod/core.html#virtualhost"><VirtualHost></a></code> then the main server userid
+ is assumed.</p>
+
+ <p><strong>User directories:</strong><br /> Requests that are
+ processed by <code class="module"><a href="./mod/mod_userdir.html">mod_userdir</a></code> will call the suEXEC
+ wrapper to execute CGI programs under the userid of the requested
+ user directory. 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. See also the
+ <code>--with-suexec-userdir</code> <a href="#install">compile
+ time option</a>.</p> </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="debug" id="debug">Debugging suEXEC</a></h2>
+
+ <p>The suEXEC wrapper will write log information
+ to the file defined with the <code>--with-suexec-logfile</code>
+ option 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.</p>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="jabberwock" id="jabberwock">Beware the Jabberwock:
+ Warnings & Examples</a></h2>
+
+ <p><strong>NOTE!</strong> This section may not be
+ complete. For the latest revision of this section of the
+ documentation, see the <a href="http://httpd.apache.org/docs/trunk/suexec.html">Online
+ Documentation</a> version.</p>
+
+ <p>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.</p>
+
+ <ul>
+ <li><strong>suEXEC Points Of Interest</strong></li>
+
+ <li>
+ Hierarchy limitations
+
+ <p class="indent">
+ 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 httpd
+ document hierarchy to take advantage of suEXEC for
+ VirtualHosts. (Example forthcoming.)
+ </p>
+ </li>
+
+ <li>
+ suEXEC's PATH environment variable
+
+ <p class="indent">
+ This can be a dangerous thing to change. Make certain
+ every path you include in this define is a
+ <strong>trusted</strong> directory. You don't want to
+ open people up to having someone from across the world
+ running a trojan horse on them.
+ </p>
+ </li>
+
+ <li>
+ Altering the suEXEC code
+
+ <p class="indent">
+ Again, this can cause <strong>Big Trouble</strong> if you
+ try this without knowing what you are doing. Stay away
+ from it if at all possible.
+ </p>
+ </li>
+ </ul>
+
+</div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="./en/suexec.html" title="English"> en </a> |
+<a href="./fr/suexec.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
+<a href="./ja/suexec.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
+<a href="./ko/suexec.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
+<a href="./tr/suexec.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
+</div><div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>This section is experimental!</strong><br />Comments placed here should not be expected
+to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div>
+<script type="text/javascript"><!--//--><![CDATA[//><!--
+var disqus_shortname = 'httpd';
+var disqus_identifier = 'http://httpd.apache.org/docs/2.4/suexec.html.en';
+(function(w, d) {
+ if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
+ d.write('<div id="disqus_thread"><\/div>');
+ var s = d.createElement('script');
+ s.type = 'text/javascript';
+ s.async = true;
+ s.src = 'http' + '://' + disqus_shortname + '.disqus.com/embed.js';
+ (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
+ }
+ else {
+ d.write('<div id="disqus_thread">Comments have been disabled for offline viewing.<\/div>');
+ }
+})(window, document);
+//--><!]]></script></div><div id="footer">
+<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
+if (typeof(prettyPrint) !== 'undefined') {
+ prettyPrint();
+}
+//--><!]]></script>
+</body></html>
\ No newline at end of file
projects / apache / blobdiff