The Rule File

The rule file (configuration file) defines how the WWW software will translate a request into a document name. For a server, it allows one to provide an extra level of name mapping above that given by links in the file system. It allows, for example, out of date names to mapped onto their more recent counterparts.

For the client, it allows access to certain servers to be remapped for example caching servers, or to local copies of the same information.

The rule file also allows access to be restricted. This is essential, to prevent, for example, unauthorized access to your password file.

By default, the rule file /etc/httpd.conf is loaded, unless specified otherwise with the -R or -r options .

Mapping and filtering

Each line consists of an operation code and one or two parameters, referred to as the template and the result. Anything on a line after and including a hash sign (#) is ignored, as are empty lines.

The server uses the top rule first, then EACH SUCCESSIVE RULE unless told otherwise by PASS or FAIL. The operation codes are as follows

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 at most one wildcard asterisk ("*"). The result string may have one wildcard only if the template has one.

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 ro fail is matched: they terminate the rule scan.

Access Authorization

From the version 2.12 on daemon supports access authorization which introduces two new rules: protect and defprot. They have the following syntax:

        defprot <template> <setupfile> <uid.gid>
        protect <template> <setupfile> <uid.gid>

<setupfile>

is a pathname for protection setup file which sets up 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 comma) to which the server should change when serving the request. These are only meaningful when the server is running as root.

These can be omitted, when they default to nobody and nogroup.

Executable Scripts

From the version 2.13 on daemon supports executable scripts on server-side. Scripts are stored in a "/htbin" directory, and called when the document name starts with the string /htbin/. The physical location of "/htbin" directory is given by htbin keyword in the rule file:

        htbin <directory>

This has to be present in the rule file in order to turn the /htbin feature on.

Index Search Facility

Server automatically calls a script to perform search, if the search script name is supplied by a search field in rule file:

        search <name>

Name is just a name (not a full pathname), the script must physically reside in htbin directory, and /htbin feature must be enabled by a htbin field in rule file.

This script is called with absolute (translated) docement pathname (from which the query was entered) as the first parameter, and the keywords as the rest of the parameters. Search script must conform to /htbin rules, that is, it has to output either a Location: field, or start its output with:

        Content-Type: foo/bar

followed by a blank line.

Suffix definitions

As well as any mapping lines in the rule file, the rule file may be used to define the data types of files with particular suffixes. The syntax

		suffix  <suffix>  <representation> <encoding> [ <quality> ]

for example:

		suffix  .pc     text/plain          7bit	1.0
		suffix	*.*     application/binary  binary	0.1
		suffix	*	text/plain	    7bit

The parameters are as follows:

<suffix>: The last part of the filename. There are two special cases. "*.*" matches to all files which have not been matched by any explicit suffixes but do contain a dot. "*" by itself matches to any file which does not match any other suffix.
<representation>: A MIME "content-type" style description of the repreentation in fact in use in the file. See the HTTP spec. This need not be a real MIME type -- it will only be used if it matches a type given by a client.
<encoding>: A MIME content transfer encoding type. Much more limited in variety than representations, basically whether the file is ASCII (7bit or 8bit) or binary. A few other encodings are allowed, and maybe extension to compression.
<quality>: Optional. A floating point number between 0.0 and 1.0 which determines the relative merits of files xxx.* which differ in their suffix only, when a link to xxx.multi is being resolved. Defaults to 1.0.

Presentation definitions

In the rule file for a client, you can define the presentation of a given data type. The syntax is

		presentation   <representation>  <command-string>

where the parameters are

<representation>: A MIME-style content type. You can use regulare MIME types, such as image/jpeg, or your own extensions which start with x-, such as image/x-tiff, application/x-my-app. See also above .
<command string>: The command needed to display a temporary file of this type. A "%s" within this string will be replaces with the name of the temporary file. Note that is any file suffix has been specified as corresenponding to this representation, then the temporarty file will be give that (or the first if there is a choice) suitable suffix.

Tim BL