Setting up a Web Server to Work with Mallard

(with details for Apache httpd.conf setup)

What sort of web server can I use?

You may use any server you like, as long as it may be configured as described below. The actual mechanism for configuring and setting up the server will vary by vendor, but you should be able to change the user id and document root of the server, set the port, etc. Note that "the server" may be a virtual server, if you are already serving other documents on the machine.

We suggest that you use a server configured to use SSL (Secure Sockets Layer) but this is not strictly required.

How does the web server work with Mallard?

Mallard is a set of CGI programs and associated library modules. The server must be set up to serve these documents. You may install a new web server without disturbing Mallard, or install a new version of Mallard without disturbing the web server. Both the web server and Mallard may be installed wherever you like. The web server relates to Mallard only in that it (1) runs as user mallard and (2) has the document root set up to serve the Mallard cgi scripts.

How do I configure the server to do that?

You will need to configure the server in the following manner:

Set the user and group to mallard.
A web server, like any other process, runs with a given user id and group id. In order to be able to access all of the Mallard program files and keep the content and user data files owned by mallard, the server must run as user mallard.
User mallard should be a regular user on the system. User mallard will need to have login access, as the Mallard Administrator will need to install or upgrade code while logged in as the mallard user, and may occasionally need to edit some files on the server with a text editor or tar files up for moving or archiving. Access to the password for user mallard should be carefully guarded - anyone with this password has essentially "superuser access" to the Mallard file tree, including all content and student information.
The relevant lines for apache are:
```
     User mallard
     Group mallard
    
```
(Note: These "relevant lines for apache" may be typed in at the top level to apply to the entire server, if Mallard is the only thing being served by the server, or inside <VirtualHost> </VirtualHost> tags if the Mallard server is merely one virtual server on the machine.)
Set the document root to $MALLARD_HOME/docs.
The document root is the head of the directory tree from which the server can serve documents. You will need to set it to $MALLARD_HOME/docs, where $MALLARD_HOME is the head of the Mallard install tree, containing the "docs" and "lib" subdirectories among other things. You must give the literal value for $MALLARD_HOME here. For example, on my server, $MALLARD_HOME is set to /usr/local/webdata/mallard .
The relevant lines for apache are:
```
     DocumentRoot "/usr/local/webdata/mallard/docs"
    
```
Set up the document root to allow (1) execution of CGI scripts, (2) following of symbolic links, and (3) directory indexing.
The CGI scripts in Mallard are located underneath the document root in $MALLARD_HOME/docs/cgi-bin. They are called, however, via symlinks named after the courses, for example $MALLARD_HOME/docs/SPANISH101. Hence we need to allow both symlinks and CGI execution. In addition, the default home page is in index.cgi, but we generally wish the Mallard URLs to end with the course name rather than specify the index.cgi. Therefore we need to allow directory indexing (setting the "default URL" for a directory). We'll specify that default URL to be "index.cgi" in the next step.
The relevant lines for apache are:
```
    # Enable cgi files ending in .cgi anywhere under the document root.
    AddHandler cgi-script .cgi

    # Mallard server document root
    <Directory "/usr/local/webdata/mallard/docs">
        Options Indexes FollowSymLinks ExecCGI
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>
    
```
Set the "default URL" for directories to be index.cgi, followed by index.html.
The main Mallard page for a course, with the frameset, is a program "index.cgi". This should be the default URL for the directory.
The relevant lines for apache are:
```
    # Find index.cgi before index.html
    DirectoryIndex index.cgi index.html index.htm
    
```
Export the environment variable $MALLARD_HOME to all CGI scripts running on the server.
Mallard makes use of many Mallard library files, which are located outside of the document root in the $MALLARD_HOME/lib directory. The course data areas for a course XXX, containing both the course content and the student data, are similarly located outside of the document root in the $MALLARD_HOME/course/XXX directory. In order for the scripts to be able to find these things, they must know where $MALLARD_HOME is on the server. $MALLARD_HOME is obviously different for each institution, so it is accessed as an environment variable. Each CGI script must have access to it.
The relevant lines for apache are:
```
    # Export the $MALLARD_HOME environment variable
    setenv MALLARD_HOME /usr/local/webdata/mallard
    
```
Set up the access logs so that they may be browsed from within Mallard with the "Logfile Analyzer" utility.
The Logfile Analyzer expects to find the server access logs (which record all hits to the server) in a file called $MALLARD_HOME/logs/access. You should set the logs so that they save in this location. The error logs (which log all server errors) can be interesting to browse as well, although you'd need to do that on the server - there isn't a Mallard interface for that.
I like to use the "combined" format (which comes with the default Apache httpd.conf file) for my access logs.
The relevant lines for apache are:
```
    # Log format stuff
    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined

    # Logs
    ErrorLog /usr/local/webdata/mallard/logs/errors
    CustomLog /usr/local/webdata/mallard/logs/access combined
    
```

The rest of the configuration settings, such as the server admin, the port, and the server URL, do not relate directly to Mallard and may be set up as you like.

All together then, what does the relevant part of your httpd.conf look like?

A snip of my httpd.conf file is given below:

# Mallard server document root
<Directory "/usr/local/webdata/mallard/docs">
    Options Indexes FollowSymLinks ExecCGI
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

# Find index.cgi before index.html
DirectoryIndex index.cgi index.html index.htm

# Enable cgi files ending in .cgi anywhere under the document root.
AddHandler cgi-script .cgi

# General setup
Port 80
DocumentRoot "/usr/local/webdata/mallard/docs"
ServerName zax.csl.uiuc.edu
ServerAdmin maiko@wocket.uiuc.edu
User mallard
Group mallard
DirectoryIndex index.cgi index.html index.htm

# Export the $MALLARD_HOME environment variable
setenv MALLARD_HOME /usr/local/webdata/mallard

# Log format stuff
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined

# Logs
ErrorLog /usr/local/webdata/mallard/logs/errors
CustomLog /usr/local/webdata/mallard/logs/access combined

How will I know if I've been successful?

After making the above edits, stop and restart the server. Then, go to the "base URL" for Mallard, which should be something like http://mallard.my_school.edu/. If you have set things up successfully, you should see the green page with the Mallard logo on it.

Questions? Comments? General harrassment? Mail it to mcovingt@staff.uiuc.edu.