granicus.if.org Git - apache/blob - docs/manual/suexec.html

   1 <html><head>
   2 <title>Apache SetUserID Support</title>
   3 </head><body>
   4
   5 <!--#include virtual="header.html" -->
   6 <h1>Apache suEXEC Support</h1>
   7
   8 <hr>
   9
  10 <h3>What is suEXEC?</h3>
  11 The <b>suEXEC</b> feature, introduced in Apache 1.2 provides the ability to
  12 run <b>CGI</b> programs under user ids different from the user id of the
  13 calling webserver. Used properly, this feature can reduce considerably the
  14 insecurity of allowing users to run CGI programs. At the same time, improperly
  15 configured, this facility can crash your computer, burn your house down and
  16 steal all the money from your retirement fund. <b>:-)</b> If you aren't
  17 familar with managing setuid root programs and the security issues they
  18 present, we highly recommend that you not consider using this feature.<p>
  19
  20 <hr>
  21
  22 <h3>Enabling suEXEC Support</h3>
  23 Having said all that, enabling this feature is purposefully difficult with
  24 the intent that it will only be installed by users determined to use it and
  25 is not part of the normal install/compile process.<p>
  26
  27 <ul>
  28 <h3>Configuring the suEXEC wrapper</h3>
  29 From the toplevel of the Apache source tree, type:&nbsp;&nbsp;<b><code>cd support [ENTER]</code></b><p>
  30 Edit the <code>suexec.h</code> file and change the following macros to match your
  31 local Apache installation.<p>
  32 <i>From support/suexec.h</i>
  33 <code>
  34 <pre>
  35 /*
  36  * HTTPD_USER -- Define as the username under which Apache normally
  37  *               runs.  This is the only user allowed to execute
  38  *               this program.
  39  */
  40 #define HTTPD_USER "www"
  41
  42 /*
  43  * LOG_EXEC -- Define this as a filename if you want all suEXEC
  44  *             transactions and errors logged for auditing and
  45  *             debugging purposes.
  46  */
  47 #define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
  48
  49 /*
  50  * DOC_ROOT -- Define as the DocuemntRoot set for Apache.  This
  51  *             will be the only hierarchy (aside from UserDirs)
  52  *             that can be used for suEXEC behaviour.
  53  */
  54 #define DOC_ROOT "/usr/local/etc/httpd/htdocs"
  55
  56 /*
  57  * NNAME -- Define this as the name for the nobody account
  58  *          on your operating system.  Most systems will just
  59  *          need the default 'nobody'.
  60  */
  61 #define NNAME "nobody"
  62
  63 /* NGID -- Define this as the *number* for the nogroup group
  64  *         on your operating system.  Most systems will have
  65  *         a -1 or -2.  Others might have something above
  66  *         65000.
  67  */
  68 #define NGID -1
  69 </pre>
  70 </code>
  71
  72 <h3>Compiling the suEXEC wrapper</h3>
  73 At the shell command prompt, type:&nbsp;&nbsp;<b><code>cc suexec.c -o suexec [ENTER]</code></b>.<p>
  74 This should create the <b><em>suexec</em></b> wrapper executable.
  75
  76 <h3>Compiling Apache for suEXEC support</h3>
  77 By default, Apache is compiled to look for the suEXEC wrapper in the following
  78 location.<p>
  79 <i>From src/httpd.h</i>
  80 <code>
  81 <pre>
  82 /* The path to the suEXEC wrapper */
  83 #ifndef SUEXEC_BIN
  84 #define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
  85 #endif
  86 </pre>
  87 </code>
  88 <p>
  89 If your installation requires location of the wrapper program in a different
  90 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>
  91
  92 <h3>Installing the suEXEC wrapper</h3>
  93 Copy the <b><em>suexec</em></b> executable created in the exercise above to the defined
  94 location for <b>SUEXEC_BIN</b>.<p>
  95 In order for the wrapper to set the user id for execution requests it must me installed
  96 as owner <b><em>root</em></b> and must have the setuserid execution bit set for file modes.
  97 If you are not running a <b><em>root</em></b> user shell, do so now and execute the following
  98 commands.<p>
  99
 100 <b><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p>
 101 <b><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p>
 102
 103 <i>Change the path to the suEXEC wrapper to match your system installation.</i>
 104 </ul>
 105
 106 <hr>
 107
 108 <a name="model"></a>
 109 <h3>Security Model of suEXEC</h3>
 110 The <b>suEXEC</b> wrapper supplied with Apache performs the following security
 111 checks before it will execute any program passed to it for execution.
 112 <ol>
 113 <li>User executing the wrapper <b>must be a valid user on this system</b>.
 114 <li>User executing the wrapper <b>must be the compiled in HTTPD_USER</b>.
 115 <li>The command that the request wishes to execute <b>must not contain a /</b>.
 116 <li>The command being executed <b>must reside under the compiled in DOC_ROOT</b>.
 117 <li>The current working directory <b>must be a directory</b>.
 118 <li>The current working directory <b>must not be writable by <em>group</em> or <em>other</em></b>.
 119 <li>The command being executed <b>cannot be a symbolic link</b>.
 120 <li>The command being executed <b>cannot be writeable by <em>group</em> or <em>other</em></b>.
 121 <li>The command being executed <b>cannot be a <em>setuid</em> or <em>setgid</em> program</b>.
 122 <li>The target UID and GID <b>must be a valid user and group on this system</b>.
 123 <li>The target UID and GID to execute as, <b>must match the UID and GID of the directory</b>.
 124 <li>The target execution UID and GID <b>must not be the privledged ID 0</b>.
 125 <li>Group access list is set to NOGROUP and the command is executed.
 126 </ol>
 127 If any of these issues are too restrictive, or do not seem restrictive enough, you are
 128 welcome to install your own version of the wrapper. We've given you the rope, now go
 129 have fun with it. <b>:-)</b>
 130
 131 <hr>
 132
 133 <h3>Using suEXEC</h3>
 134 After properly installing the <b>suexec</b> wrapper executable, you must kill and restart
 135 the Apache server. A simple <code><b>kill -1 `cat httpd.pid`</b></code> will not be enough.
 136 Upon startup of the webserver, if Apache finds a properly configured <b>suexec</b> wrapper,
 137 it will print the following message to the console.<p>
 138
 139 <code>Configuring Apache for use with suexec wrapper.</code><p>
 140
 141 If you don't see this message at server startup, the server is most likely not finding the
 142 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>
 143
 144 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
 145 different from the main server user id, all requests for CGI resources will be executed as
 146 the <b>User</b> and <b>Group</b> defined for that <b>&lt;VirtualHost&gt;</b>. If only one or
 147 neither of these directives are specified for a <b>&lt;VirtualHost&gt;</b> then the main
 148 server userid is assumed.<p>
 149
 150 <b>suEXEC</b> can also be used to to execute CGI programs as the user to which the request
 151 is being directed. This is accomplished by using the <b>~</b> character prefixing the
 152 user id for whom execution is desired. The only requirement needed for this feature to work
 153 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.
 154
 155 <hr>
 156
 157 <h3>Debugging suEXEC</h3>
 158 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,
 159 have a look at this log and the error_log for the server to see where you may have gone astray.
 160 <!--#include virtual="footer.html" -->
 161
 162 </BODY>
 163 </HTML>
 164