[APACHE DOCUMENTATION]

Apache suEXEC Support


What is suEXEC?

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.


Enabling suEXEC Support

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.


Security Model of suEXEC

The suEXEC wrapper supplied with Apache performs the following security checks before it will execute any program passed to it for execution.
  1. User executing the wrapper must be a valid user on this system.
  2. User executing the wrapper must be the compiled in HTTPD_USER.
  3. The command that the request wishes to execute must not contain a /.
  4. The command being executed must reside under the compiled in DOC_ROOT.
  5. The current working directory must be a directory.
  6. The current working directory must not be writable by group or other.
  7. The command being executed cannot be a symbolic link.
  8. The command being executed cannot be writable by group or other.
  9. The command being executed cannot be a setuid or setgid program.
  10. The target UID and GID must be a valid user and group on this system.
  11. The target UID and GID to execute as, must match the UID and GID of the directory.
  12. The target execution UID and GID must not be the privledged ID 0.
  13. Group access list is set to NOGROUP and the command is executed.
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. :-)

Using suEXEC

After properly installing the suexec wrapper executable, you must kill and restart the Apache server. A simple kill -1 `cat httpd.pid` 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.

Configuring Apache for use with suexec wrapper.

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 User and Group directives in VirtualHost definitions. By setting these directives to values different from the main server user id, all requests for CGI resources will be executed as the User and Group defined for that <VirtualHost>. If only one or neither of these directives are specified for a <VirtualHost> then the main server userid is assumed.

suEXEC 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 ~ 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 security checks above.


Debugging suEXEC

The suEXEC wrapper will write log information to the location defined in the suexec.h 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.
The manual translated into Japanese is here.

Index