Rules In The Configuration File

Rules define the mapping between virtual URLs and physical file names. Currently the following rules are understood:

Map - Map URLs to actual files
Pass - Accept a request
Fail - Fail a request
Redirect - Redirect a request
Protect - Set up protection
DefProt - Default protection setup
Exec - Executable server scripts

Mapping, Passing and Failing

There are three main rules: Map, Pass and Fail. The server uses the top rule first, then each successive rule unless told otherwise by a Pass or a Fail rule.

Map template result: If the address matches the template, use the result string from now on for future rules.
Pass template: If the address maches the template, use it as it is, porocessing no further rules.
Pass template result: If the string matches the template, use the result string as it is, processing no futher rules.
Fail template: If the address matches the template, prohibit access, processing no futher rules.

The template string may contain wildcards (asterisks) *. (Versions earlier than 3.0 support only a single wildcard.) The result string may have wildcards only if the template has them. In this case they expand to matched strings in respective order.

Whitespace, (literal) asterisks and backslashes are allowed in templates if they are preceded by a backslash.

The tilde character (see user-supported directories) just after a slash (in other words in the beginning of a directory name) has to be explicitly matched, i.e. wildcard does not match it.

When matching,

Rules are scanned from the top of the file to the bottom.
If a request matches a Map template exactly, the result string is used instead of the original string and applied to successive rules.
If the request maches a Map template with wildcard, then the text of the request which matches the wildcard is inserted in place of the wildcard in the result string to form the translated request. If the result string has no wildcard, it is used as it is.
When a Map substitution takes place, the rule scan continues with the next rule using the new string in place of the request. This is not the case if a Pass or Fail is matched: they terminate the rule scan.

Redirecting Requests Elsewhere

When documents, or entire trees of documents, are moved from one server to another, you can use Redirect rule to tell httpd to redirect the request to another server. If the client program is smart enough user won't even notice that the document is retrieved from a different server.

Redirect template result: Document matching template is redirected to result, which must be a full URL (i.e. containing http: and the host name).

Example

        Redirect  /hypertext/WWW/*  http://www.cern.ch/WebDocs/*

This redirects everything starting with /hypertext/WWW to host www.cern.ch into virtual directory /WebDocs. For example, /hypertext/WWW/ would be redirected to http://www.cern.ch/WebDocs/.

Setting Up User Authentication and Document Protection

Documents are protected by Protect and DefProt rules. Their syntax is the following:

DefProt template setup-file [uid.gid]: Any document matching the template is associated with protection setup-file. The documents are not yet taken to be protected, but they may become protected by an existing access control list file in the same directory as the requested file, or by later matching a Protect rule. If that Protect rule doesn't specify setup-file, the one from the latest DefProt rule is used.
Protect [template setup-file [uid.gid]]: Any document matching template is protected. The type of protection is defined in finer detail in setup-file.
If setup-file is not specified the one from previous matched DefProt rule will be used. If none have matched access to the file is forbidden.

setupfile is always a full pathname for the protection setup file which specifies the actual protection parameters.

Setup file can be omitted from Protect rule, but it is obligatory in DefProt rule. If setup file is omitted it is not possible to give the uid.gid part, either.

uid.gid are the Unix user id and group id (either by name or by number, separated by a dot) to which the server should change when serving the request. These are only meaningful when the server is running as root. If they are missing they default to nobody.nogroup.

Note: Uid and gid are inherited from DefProt rule to Protect rule only when the setup-file is also inherited. If setup-file is specified for Protect rule but uid.gid is not, they default to nobody.nogroup regardless of the previous DefProt rule.

This is to avoid accidentally running the server under wrong user id with wrong setup file. This information should logically go into the protection setup file, but for safety reasons it cannot be done, because a non-trustworthy collaboration could specify it to be root. This way only the main webmaster can control user and group ids.

Executable Server Scripts

Document address is mapped into a script call by Exec rule:

        Exec template script

In both template and script there must be a * wildcard, that matches everything starting from the script filename. This is to enable httpd to know what is the script name and what is the extra path information to be passed to the script.

Example

You want to map everything starting with /your/url/doit to execute the script /usr/etc/www/htbin/doit. You do this by saying:

        Exec  /your/url/*  /usr/etc/www/htbin/*

Here asterisk matches the script name doit (and everything else that follows it). Usually people use some fixed keyword in front of the pathname in URL to point out that the document is actually a script call. Often this keyword is /htbin. That is, usually your Exec rule looks like this:

        Exec  /htbin/*  /usr/etc/www/htbin/*

and all the URLs pointing to the scripts start with /htbin, for example /htbin/doit in the previous example.

Historical Note (HTBin Rule)

W3C httpd versions 2.13 and 2.14 had a hard-coded handling of URL pathnames starting /htbin that mapped them to scripts in a directory specified via HTBin rule:

        HTBin /your/htbin/directory

This is still handled automatically by httpd, by translating it to its equivalent Exec form:

        Exec /htbin/*  /your/htbin/directory/*

Always use Exec instead -- it is more general.

httpd@w3.org, July 1995