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.

Next: User IDs Suexec Will Use »