Backtalk Installation Guide

Part VB: Apache Configuration with Unix Accounts

Version 1.3.29

Prev: Part IV: Installation
Next: Part VI: Cron Configuration

If you are installing a system using Backtalk accounts, read the other version of this page.

You probably need to make some adjustments to the configuration of your http server before Backtalk will work properly. We have no idea how to do Unix authentication with httpd servers other than Apache, so we strongly suggest using Apache.

(1) Install Mod_Auth_External

If you selected --authtype=shadow then you need to set up Apache for authenticating out of the shadow password file. We suggest that the freeware mod_auth_external be used for this. It can be obtained from http://www.unixpapa.com/mod_auth_external.html. This distribution includes the 'pwauth' program which you will need. If you got mod_auth_external from someplace else, and it doesn't include pwauth get ours instead.

Mod_auth_external comes with detailed instructions for how to link it into Apache. Follow those.

If you selected --authtype=passwd then it would probably make sense to use something like mod_auth_system or mod_auth_pam. We've never tried this, and in most cases we think you'd be better off upgrading your system to one that uses a shadow password file. If you're aren't feeling adventurous enough to figure out how to use these other modules, it would work OK to just install mod_auth_external and pwauth as described here.

(2) Install Pwauth

The pwauth program is an external suid-root program that is run by mod_auth_external to do authentications out of a Unix shadow file (or through PAM). It is part of the mod_auth_external distribution but it was originally written for Backtalk.

Follow the installation instructions that come with pwauth. If you built Backtalk with the --lastlog=unix option, then you'll probably want to define UNIX_LASTLOG in pwauth's config.h file. If you didn't, don't.

Install the program in a sensible place (possibly in Backtalk's libexec directory). Set it up to be setuid-root so it can read the shadow file.

(3) Configure Apache for Pwauth

Find Apache's configuration file, named 'httpd.conf'. You'll need to add the lines:

       AddExternalAuth pwauth /full/path/to/pwauth
       SetExternalAuthMethod pwauth pipe

If you are using virtual servers, these lines need to go into the appropriate virtual server block. Otherwise you can just put them anywhere near the end of the file.

(4) Enable Authentication

The Backtalk installation scripts will have created two subdirectories under your CGI directory, one named 'pw' the other named 'adm'. Into these directories it has placed some programs that should only be runnable by authenticated users, and it has placed some files named '.htaccess' which configure the authentication for those directories.

As distributed, Apache will ignore the '.htaccess' files. To enable them, we need to make a slight change in the configuration.

To do this, locate the 'httpd.conf' configuration file for Apache and edit it. Find the section of the configuration file that configures the options on the cgi-bin directory. It probably looks something like this:

    <Directory "/home/httpd/cgi-bin">
        AllowOverride None
        Options ExecCGI
        Order allow,deny
        Allow from all
    </Directory>

Change the 'AllowOverride' line to say

        AllowOverride AuthConfig

This says that '.htaccess' files may override the authentication configuration settings for this directory and its subdirectories.

(5) Restart Apache

Tell the currently running apache to reload its configuration file, so the new settings are activated. If your system has the 'apachectl' program installed, do:

        apachectl restart

For Redhat 6.1, which doesn't have 'apachectl', do instead:

        /etc/rc.d/init.d/httpd restart

(6) Test Authentication

If you aren't confident that you have Apache and the Backtalk authentication system all correctly installed, then you may want to run some tests by using your browser to run Backtalk's little cgitest script.

The URLs of the cgitest program will be

cgiurl/cgitestcgisuffix/foo?bar
cgiurl/pw/cgitestcgisuffix/foo?bar
cgiurl/adm/cgitestcgisuffix/foo?bar

For example, if you configured cgiurl to http://your.host.name/cgi-bin/backtalk and did not set cgisuffix, then the URLs would be

http://your.host.name/cgi-bin/backtalk/cgitest/foo?bar
http://your.host.name/cgi-bin/backtalk/pw/cgitest/foo?bar
http://your.host.name/cgi-bin/backtalk/adm/cgitest/foo?bar

Try hitting these URLs with your browser.

The first URL is just to test that you can run CGI scripts and that your http server is vaguely sane. The output will look something like:

environment variables:
HTTP_USER_AGENT=Mozilla/4.61 [en] (X11; I; Linux 2.2.12-20 i686)
PATH_INFO=/foo
PATH_TRANSLATED=/home/httpd/html/foo
QUERY_STRING=bar
REMOTE_ADDR=209.142.241.230
REMOTE_HOST=undefined
REMOTE_USER=undefined
SCRIPT_NAME=/cgi-bin/backtalk/cgitest
httpd id:
uid=99(nobody) gid=99(nobody) groups=99(nobody)

If you instead only get an error message or no output at all, something is definitely wrong. The error messages displayed by the browser are often vague. Check the http server's error log for a more detailed message. If the cgitest program was not found, the log file will get the path name it looked at. Is the cgitest program there and correctly permitted? If it is looking under the document root, you may need to add a ScriptAlias for the `cgi-bin' directory (for Apache, this should be in the httpd.conf file.

If you are seeing the contents of the cgitest program instead of its output, then Apache is not recognizing it as a CGI program and is just displaying the file instead of running it. Your server may be configured to require a .cgi suffix on CGI program files.

If it runs, you should confirm that

HTTP_USER_AGENT is a string describing your browser.
PATH_INFO is ``/foo'' (as given in the URL above).
PATH_TRANSLATED is the full path to your document root followed by ``/foo''.
QUERY_STRING is ``bar'' (as given in the URL above).
REMOTE_ADDR is the IP number of the host your browser is running on.
REMOTE_HOST is undefined or the name of the host your browser is running on (whether or not it is defined depends on you server's configuration and doesn't particularly matter to Backtalk).
REMOTE_USER is undefined.
SCRIPT_NAME is ``/cgi-bin/backtalk/cgitest'' (or whatever else was between the hostname and the ``/foo'' in the URL you used).
The http id is the one you defined in the httpd-id configuration setting.

The second two URLs run the same test script, but authentication should be required for them. Your browser should pop up a login window before showing the output of the program. Any valid Unix login and password should work. The output should be similar to that shown above, except that REMOTE_USER should be the name of the account you logged into.

If you are not asked for authentication and REMOTE_USER is shown as undefined, then Apache is not recognizing the .htaccess file. Check that you have `AllowOverride AuthConfig' set for the cgi-bin directory.

Note that once you have authenticating, if you run the same program again, or another program in the same directory, you will not be asked to log in again. Your browser remembers your old authentication and automatically resends it. To log in as a different user, you need to exit and restart the browser. This is, in fact, the sole purpose of the `adm' subdirectory. With two links to Backtalk in directories with different AuthNames, it is possible for a person to be logged on simultaneously as two different users. This is especially useful for conference administrators, who may want to access the administration account without exiting their personal accounts. That's why the second directory is called `adm', though the link to Backtalk in there does not actually have any special properties.

Prev: Part IV: Installation
Next: Part VI: Cron Configuration