The simplest way to verify that suexec is functioning properly is to install a script that will tell you the username under which it's being invoked.

    # cd /usr/local/web/apache/cgi-bin/
    # cat > showuser.cgi << EOS
    #!/bin/sh
    echo "Content-type: text/plain"
    echo ""
    echo "Username="`whoami`
    EOS
    # chmod 755 showuser.cgi
    # chown user1.group1 . ./showuser.cgi
  

(By calling it "showuser.cgi" you can copy it directly into a user's directory without having to rename it. Filename extensions on scripts in ScriptAliased directories are ignored, so it does no harm to keep the .cgi extension.)

Note that the cgi-bin/ directory isn't under the DocumentRoot, which is why the --suexec-docroot value was bumped up one level--that way it covers both the ServerRoot (including the cgi-bin/ directory) and the DocumentRoot.

Since there are two ways in which suexec can be invoked, you should test both of them:

Server-wide suexecution

First, create a <VirtualHost> container (or use an existing one) in your server configuration files, and add User and Group directives to it. Pick some username and group that are different from the normal server user. Next, make sure that you have a ScriptAlias directive that points to the directory where you put your test script. Next, make sure that the cgi-bin/ directory and the test script are owned by the user and group you've chosen, and are mode 755. Finally, (re)start the Apache server and request the test script with some URL like <URL:http://myvirtualhost/cgi-bin/showuser.cgi>. If you get an error, examine the server error log and the suexec log.

User directory suexecution

To test that suexec will properly handle a CGI script in a user's directory, copy your showuser.cgi script into that user's public_html/ directory, make sure that both the script and the public_html/ directory itself are mode 755 and owned by the user, and then request the script with a URL such as <URL:http://myhost/~user/showuser.cgi>. If you get an error page, look at the Apache and suexec logs.

Debugging

Debugging a suexec problem can be frustrating, particularly since almost any problem with a CGI script in a suexec-enabled environment turns out to be related to the wrapper.

The typical warning signal of a suexec problem is a request for a CGI script that results in a '500 Internal Server Error' page. The appropriate response behaviour to such an error is to look in the server's error log. Unfortunately, because the wrapper is applying its own restrictions and rules on the script, the server log may be quite unrevealing, containing only a single line such as the following for the failed request:

[Sun Dec 26 20:02:55 1999] [error] [client n.n.n.n] Premature end of script headers: script

The real error message will be found in your suexec log (which is located at /usr/local/web/apache/logs/suexec_log, according to the assumptions section of this article). The suexec error message may look like this:

    [1999-12-26 20:02:55]: uid: (user/user) gid: (group/group) cmd: test.cgi
    [1999-12-26 20:02:55]: command not in docroot (/home/user/public_html/test.cgi
  

Here are a couple of other common suexec error messages:

• directory is writable by others: (path)
• target uid/gid (uid-1/gid-1) mismatch with directory (uid-2/gid-2) or program (uid-3/gid-3)

If it's still not clear what's going wrong, review the list of requirements and make sure they're all being met.

Next: "Danger, Will Robinson!" »