Apache HTTP Server Version 2.5
+
-
-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. -
- - - --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 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 the Apache Group hopes to limit suEXEC installation only to those -who are careful and determined enough to use it. -
- --Still with us? Yes? Good. Let's move on! -
- - - --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: -
- 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. --
- This is to ensure that the user executing the wrapper is truly a user of the - system. --
- Is this user the user allowed to run this wrapper? Only one user (the - Apache user) is allowed to execute this program. --
- Does the target program contain a leading '/' or have a '..' backreference? - These are not allowed; the target program must reside within the Apache - webspace. --
- Does the target user exist? --
- Does the target group exist? --
- Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. --
- 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. --
- Presently, suEXEC does not allow the 'root' group to execute CGI/SSI - programs. --
- 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. --
- 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. --
- If it doesn't exist, it can't very well contain files. --
- 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? --
- We don't want to open up the directory to others; only the owner user - may be able - to alter this directories contents. --
- If it doesn't exists, it can't very well be executed. --
- We don't want to give anyone other than the owner the ability to - change the program. --
- We do not want to execute programs that will then change our UID/GID again. --
- Is the user the owner of the file? --
- 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). --
- Here is where suEXEC ends and the target program begins. --
-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 -"Beware the Jabberwock" -section of this document. -
- - - --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:
-cd support [ENTER]
-
-Edit the suexec.h file and change the following macros to
-match your local Apache installation.
-
-From support/suexec.h -
- /* - * 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" -- - -
-COMPILING THE SUEXEC WRAPPER
-You now need to compile the suEXEC wrapper. At the shell command prompt,
-after compiling Apache,
-type: make suexec[ENTER].
-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/include/httpd.h -
- /* The path to the suExec wrapper, can be overridden in Configuration */ - #ifndef SUEXEC_BIN - #define SUEXEC_BIN HTTPD_ROOT "/sbin/suexec" - #endif -- - -
-If your installation requires location of the wrapper program in a different
-directory, either add -DSUEXEC_BIN=\"</your/path/to/suexec>\"
-to your CFLAGS (or edit src/include/httpd.h) and recompile your Apache server.
-See Compiling and Installing Apache
-(and the INSTALL file in the source distribution)
-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.
-
-cp suexec /usr/local/apache/sbin/suexec [ENTER]
-
-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. -
- -
-chown root /usr/local/apache/sbin/suexec [ENTER]
-
-chmod 4711 /usr/local/apache/sbin/suexec [ENTER]
-
-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. - -
- -
-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.
-
-NOTE! This section may not be complete. For the latest -revision of this section of the documentation, see the Apache Group's -Online Documentation -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. -
- 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.) --
- 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. --
- Again, this can cause Big Trouble if you try - this without knowing what you are doing. Stay away from it - if at all possible. --
Apache HTTP Server Version 2.5
+
The suEXEC feature provides users of the Apache + HTTP Server 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.
+
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.
+ +First, it is assumed that you are using a UNIX + derivative 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 HTTP Server development team for consideration.
+ +Fourth, and last, it has been the decision of + the Apache HTTP Server development team to NOT 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.
+ +Still with us? Yes? Good. Let's move on!
+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 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.
+ +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:
+ ++ This is to ensure that the user executing the wrapper is + truly a user of the system. +
++ 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. +
++ Is this user the user allowed to run this wrapper? Only + one user (the Apache user) is allowed to execute this + program. +
+
+ 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 --with-suexec-docroot=DIR
+ below).
+
+ Does the target user exist? +
++ Does the target group exist? +
+
+ suEXEC does not allow root
+ to execute CGI/SSI programs.
+
+ 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. +
+
+ Presently, suEXEC does not allow the root
+ group to execute CGI/SSI programs.
+
+ 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. +
++ 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. +
++ 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. +
+
+ 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 UserDir, is the requested directory
+ within the directory configured as suEXEC's userdir (see
+ suEXEC's configuration options)?
+
+ We don't want to open up the directory to others; only + the owner user may be able to alter this directories + contents. +
++ If it doesn't exists, it can't very well be executed. +
++ We don't want to give anyone other than the owner the + ability to change the CGI/SSI program. +
++ We do not want to execute programs that will then change + our UID/GID again. +
++ Is the user the owner of the file? +
++ 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). +
++ Here is where suEXEC ends and the target CGI/SSI program begins. +
+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.
+ +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 "Beware the Jabberwock" section of this + document.
+Here's where we begin the fun.
+ +suEXEC configuration
+ options
+
--enable-suexec--with-suexec-xxxxx option has to be provided
+ together with the --enable-suexec option to let
+ APACI accept your request for using the suEXEC feature.--with-suexec-bin=PATHsuexec binary must be hard-coded
+ in the server for security reasons. Use this option to override
+ the default path. e.g.
+ --with-suexec-bin=/usr/sbin/suexec--with-suexec-caller=UID--with-suexec-userdir=DIRUserDir
+ 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. Default value is
+ "public_html".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!--with-suexec-docroot=DIRUserDirs) that can be used for suEXEC behavior. The
+ default directory is the --datadir value with the suffix
+ "/htdocs", e.g. if you configure with
+ "--datadir=/home/apache" the directory
+ "/home/apache/htdocs" is used as document root for the
+ suEXEC wrapper.--with-suexec-uidmin=UID--with-suexec-gidmin=GID--with-suexec-logfile=FILEsuexec_log" and located in your standard logfile
+ directory (--logfiledir).--with-suexec-safepath=PATH/usr/local/bin:/usr/bin:/bin".If you have enabled the suEXEC feature with the
+ --enable-suexec option the suexec binary
+ (together with httpd itself) is automatically built if you execute
+ the make command.
After all components have been built you can execute the
+ command make install to install them. The binary image
+ suexec is installed in the directory defined by the
+ --sbindir option. The default location is
+ "/usr/local/apache2/bin/suexec".
Please note that you need root
+ privileges for the installation step. In order
+ for the wrapper to set the user ID, it must be installed as
+ owner root and must have the setuserid
+ execution bit set for file modes.
Although the suEXEC wrapper will check to ensure that its
+ caller is the correct user as specified with the
+ --with-suexec-caller configure
+ 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.
If for example, your web server is configured to run as:
+ ++User www +Group webgroup ++ + +
and suexec is installed at
+ "/usr/local/apache2/bin/suexec", you should run:
+ chgrp webgroup /usr/local/apache2/bin/suexec
+ chmod 4750 /usr/local/apache2/bin/suexec
+
This will ensure that only the group httpd runs as can even + execute the suEXEC wrapper.
+ +Upon startup of httpd, it looks for the file
+ suexec in the directory defined by the
+ --sbindir 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:
+ [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)
+
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.
+ +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.
+If you want to disable suEXEC you should kill and restart
+ httpd after you have removed the suexec file.
Requests for CGI programs will call the suEXEC wrapper only if
+ they are for a virtual host containing a SuexecUserGroup directive or if
+ they are processed by mod_userdir.
Virtual Hosts:
One way to use the suEXEC
+ wrapper is through the SuexecUserGroup directive in
+ VirtualHost definitions. By
+ setting this directive 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 this
+ directive is not specified for a <VirtualHost> then the main server userid
+ is assumed.
User directories:
Requests that are
+ processed by mod_userdir 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 security
+ checks above. See also the
+ --with-suexec-userdir compile
+ time option.
The suEXEC wrapper will write log information
+ to the file defined with the --with-suexec-logfile
+ 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.
NOTE! This section may not be + complete. For the latest revision of this section of the + documentation, see the Online + Documentation 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.
+ ++ 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.) +
++ 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. +
++ Again, this can cause Big Trouble if you + try this without knowing what you are doing. Stay away + from it if at all possible. +
+