Using Apache with Suexec on Linux

By: Ken Coar
Friday, January 21, 2000 01:07:47 PM EST
URL: http://www.linuxplanet.com/linuxplanet/tutorials/1445/1/

Executing CGI Scripts as Other Users

The Apache Web server, like most if not all of the others in common use today, lets you execute arbitrarily complex operations through the use of CGI scripts. These can involve database lookups, system administration functions, real-time control of machinery, online payments, or almost anything else you can think of.

Ordinarily, all of these things occur in the context of the user running the Apache server itself (typically nobody on Linux systems). This is fine when you're using a system that is owned and used by a single entity...but what if you're an ISP with multiple companies being hosted on your system? Or an educational institution with faculty who want to be able to execute their own scripts? Either everything has to be accessible to the Apache nobody user, or you have to run multiple instances of Apache on multiple ports and IP addresses, one of each per user, with the concomitant confusion of configuration files.

On the other hand, if the server is to be allowed to change its identity, it needs to be done in a controlled manner, so that the chance of compromising your system's security is kept to a minimum. (Remember, Apache is usually started as root and only changes to nobody later!)

The suexec (pronounced 'SUE-ex-Ek') tool helps make this possible. It's found in the src/support/ directory under your Apache source tree.

Assumptions in This Article
For the rest of this article, I'm going to make the following assumptions:

1. your Apache source tree starts at ./apache-1.3/
2. your Apache ServerRoot is /usr/local/web/apache
3. your Apache DocumentRoot is /usr/local/web/htdocs
4. the username under which Apache runs (the value of the User directive in your httpd.conf file) is nobody

All of the cd and other shell commands in this article that refer to directories use these locations.

How Does Suexec Work?

Since suexec works by wrapping an operation up in a package executed under a different username, it's called a wrapper. In order to execute a script under the auspices of the wrapper, the Apache server creates a child process running the suexec binary and passes the particulars to it. The wrapper verifies that all the security requirements are met, edits the list of environment variables so that only the ones on its 'trusted' list are available, closes its logfile, and calls some flavour of execv(2) to load the script into the edited process environment, replacing suexec itself.

Requirements For suexec Operation
Since suexec is used to run applications on your system on behalf of arbitrary people out on the Web, it's very paranoid about doing anything that might compromise your system's security. Here is a list of the conditions suexec requires to be met before it will proceed; if any don't measure up, the wrapper will log an error and not execute the script.

• suexec must be invoked with the correct number of arguments. If it isn't, it assumes someone is trying to penetrate your system by running it outside the Apache environment.
• The username/UID invoking suexec must be a valid user; that is, it must be listed in the /etc/passwd file. If it isn't, something's not quite right--and when in doubt, punt.
• The username executing the wrapper must be the one that was compiled into it when it was built. Again, a mismatch here is interpreted as someone trying to use suexec in other than the prescribed way.
• The requested script must be a valid Web-space reference relative to the user's directory or the DocumentRoot; it cannot be an absolute filesystem path (i.e., it cannot start with a "/") and cannot include any up-level references (i.e., no "../" references either).
• The username and group under which the script is to be run must be valid, cannot be 'root', and must be above the minimum UID and GID values (set with the --suexecuidmin and --suexec-gidmin options to the configure script, which both default to 100). In addition, the group must be a valid name, and not just a numeric GID.
• The wrapper must be able to change its idenity to the requested username and group.
• The script (and obviously the directory in which it lives) must actually exist and the wrapper must be able to chdir() to the directory.
• If the script isn't from a ~username request, the script directory must be under the directory specified by DOC_ROOT (defined by the --suexec-docroot option to configure).
• The permissions on the specified script and its parent directory must not allow write access to either the group or the other categories.
• The script file cannot be setuid or setgid.
• The script and the directory must be owned by the user and group as which it is to be executed.
• The script must be executable by the user.
• suexec must be able to allocate memory in which to reproduce the environment variable list.

As you can see, the requirements for execution are pretty stringent. The sheer number of things that can go wrong argues for the use of the wrapper only when it's really necessary.

Enabling suexec

The suexec wrapper isn't turned on or off by any particular Apache directive setting. Instead, when the Apache server is compiled, one of the constants set (SUEXEC_BIN) is a string pointing to the location of the suexec binary. When the server starts, it looks for the binary at that location; if it's found, suexec is enabled--not otherwise. This is very important.

This means that even a normal Apache build that was performed without any thought given to using the wrapper can suddenly become suexec-enabled if a properly protected suexec binary is put into place between server restarts. In the master sources, the default value of SUEXEC_BIN is set to "$HTTPD_ROOT/sbin/suexec"; the default value of HTTPD_ROOT is platform-specific:

You may change the values of either--or both--of the HTTPD_ROOT and SUEXEC_BIN constants when you recompile the Apache server.

If Apache does find the wrapper, it reports it in the server error log like this:

[Thu Dec 30 01:24:43 1999] [notice] suEXEC mechanism enabled (wrapper: /usr/local/web/apache/bin/suexec)

Up until Apache version 1.3.11, there was no way to be sure where a compiled Apache server is going to be looking for the suexec binary. As of 1.3.11, though, it's part of the 'compiled modules' report displayed by the '-l' switch:

    % /usr/local/web/apache/bin/httpd -l
    Compiled-in modules:
      http_core.c
      mod_so.c
    suexec: enabled; valid wrapper /usr/local/web/apache/bin/suexec
  

The 'enabled; valid' notation means that the wrapper is actually present in the indicated location, and the permissions are correct. If the wrapper isn't there, or the permissions are wrong, the output will indicate that suexec is disabled.

Compiling Suexec

Because most of suexec's control parameters are defined at compile-time, the only way to change them is to recompile. And since the wrapper works very closely with the Apache Web server--to the point of both applications having to share some compile-time definitions--the way to recompile suexec is to recompile all of Apache. If you've never done this before, you can see a brief treatment of the process in the "Building Apache at Lightspeed" section of this article.

There are several suexec-specific options to the apache-1.3/configure script. Here they are:

--enable-suexec

The presence of this option on the command line simply informs the configure script that you want the wrapper to be built as well. Without this option, suexec will not be built, even if there are other suexec options on the command line.

--suexec-caller=username

This must be the username under which your Apache server runs; that is, the one specified on the User directive outside all <VirtualHost> containers. If suexec is invoked by any other user, it assumes it's some sort of probing attempt and fails to execute (after logging the user mismatch).

The default username is www.

--suexec-docroot=path

This specifies the ancestor directory under which all CGI scripts need to reside in order to be acceptable to suexec. (This restriction doesn't apply to scripts activated by ~username-style URLs.) If you have multiple virtual hosts using suexec, their DocumentRoots (if you're using .cgi files) must all be located somewhere in the hierarchy under this directory, or else the wrapper will assume someone is trying to execute something unexpected and will log it as an intrusion attempt. ScriptAliased directories must be under this hierarchy as well, and this is in fact more important for them since they commonly aren't under the DocumentRoot.

The default value for this option is PREFIX/share/htdocs, where 'PREFIX' comes from the value of the --prefix option, explicit or implied.

--suexec-gidmin=gid

Another one of suexec's restrictions is that the user it's being asked to execute the script as mustn't be considered 'privileged.' On Linux and other Unix-like systems this generally means that it mustn't be the root user, but suexec takes this a step further and will refuse to execute as any user with a group ID less than the value of this option.

The default value for this option, if not specified, is 100.

--suexec-logfile=filename

This specifies the name of the file to which the wrapper will report errors and successful invocations. It is opened and accessed as root, but closed before control is passed to the script.

The default for this option is PREFIX/var/log/suexec_log, where 'PREFIX' is the value from the --prefix option.

--suexec-safepath=path-list

Not only is the list of environment variables examined and sanitized before the script is invoked, but the default PATH is set to a known list of directories as well. This list is hard-coded at compile-time, and is defined by this option.

The default value for --suexec-safepath is /usr/local/bin:/usr/bin:/bin.

--suexec-uidmin=uid

As with the --suexec-gidmin option described earlier, this option is used to inform suexec of forbidden UID values. If a request is made that would result in the execution of a script by a user with a UID equal to or less than this value, the wrapper will log the fact and not process the request. This foils things like a request for ~root/script.

The default value for this option is 100.

--suexec-umask=octal-umask

This option defines the default permission mode to be applied to files created by the script (if it doesn't explicitly set them itself). The umask is specified as a three-digit octal number indicating which permission bits should not be set; see the description of the umask(1) command for more details.

If this option isn't defined at compile-time, at run-time the suexec wrapper will inherit the umask setting from the parent Apache server process.

--suexec-userdir=path

This option specifies the subdirectory underneath a user's home directory that suexec will use to find scripts for ~username-style URLs. This needs to match the setting of the UserDir directive in your server configuration files.

Note: suexec can only handle simple subdirectory expressions. The more complex pattern-handling capabilities of the mod_userdir module (which implements the UserDir directive) cannot be used with the suexec wrapper.

The default --suexec-userdir setting is public_html.

If you want to change the location of the suexec binary, you can do so by adding a new definition of SUEXEC_BIN to the compilation flags:

    % env CFLAGS="-Wall -DSUEXEC_BIN=\"/usr/local/web/apache/suexec\"" \
    >  ./configure --enable-suexec ...
  

You should be extremely cautious about changing other definitions, such as HTTPD_ROOT, however, since suexec isn't the only part of Apache that uses them.

User IDs Suexec Will Use

Since the point of suexec is to handle certain Web requests under a different identity than the Apache server user, there needs to be some way to specify just which user. There are two places from which Apache will draw this information:

• The username from URLs such as <URL:http://somehost.com/~username/foo.cgi>,
  OR
• The User and Group directives in the server configuration file, httpd.conf.

The username to use is determined by checking these in the above order.

The User and Group directives are ordinarily ignored inside <VirtualHost> containers, but in a suexec-enabled server they take on new meaning for the virtual host, defining the identity under which CGI scripts requested through that host will be executed. If a virtual host doesn't have a User directive, it inherits the server-wide value (which defines the username under which the server itself is running) which will probably result in normal, non-suexec-enabled behaviour.

Incorporating Suexec Into Your Apache Server
If you have an Apache 1.3 server binary, it's capable of using a suexec wrapper if it finds one in the expected place. (Until Apache 1.3.11, there was no convenient way to find out what the 'expected place' is; as of version 1.3.11, you can find out the value of the SUEXEC_BIN compile-time constant, and whether there's a valid wrapper at that location, with the 'httpd -l' runtime switch.)

If you're working with an Apache server that you inherited, or installed as part of a package, you might not be sure whether suexec is in place or being used. If you want to be sure about it, the best thing to do is to use the Apache build procedure, which will dot the Is and cross the Ts when you 'make install'.

The main mechanism suexec uses to ensure safety is to rely on a bunch of settings made at compile-time. Likewise, the only way Apache can be made to even think about using suexec is it if has been compiled with that in mind. This means that you'll probably need to compile both the Apache server and suexec yourself. This is easily done as part of the normal Apache build. Just use the following command and the rest is easy:

    % cd ./apache-1.3/
    % ./configure \
    >        --enable-shared=max \
    >        --enable-module=most \
    >        --with-layout=Apache \
    >        --prefix=/usr/local/web/apache \
    >        --with-port=80 \
    >        --suexec-enable \
    >        --suexec-caller=nobody \
    >        --suexec-docroot=/usr/local/web