Configuration File of CERN httpd

In This Section...

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

The configuration file also allows access to be restricted. This is essential, to prevent, for example, unauthorized access to your private documents.

Note: The configuration file is not essential if you want to just export one directory tree, but then you must remember to specify the exported directory in command line: 

        httpd -p 80 /your/exported/directory
The server guesses the data types of file from the file suffix. A configuration file is necessary to specify any data types which are not in the default set of suffixes. However, the default set is quite extensive.

Default Configuration File

 By default, the configuration file /etc/httpd.conf is loaded, unless specified otherwise with the -r command line option: 
        httpd -p 80 -r /your/own/httpd.conf
See also: example rule files.

Comments in Configuration File

 Each line consists of an operation code and one or two parameters, referred to as the template and the result. Lines starting with a hash sign # are ignored, as are empty lines.

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

When matching,

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
VERY IMPORTANT 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 mathes 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)

CERN 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.

Index Search Facility

 Server automatically calls a script to perform search, if the absolute pathname of search script is supplied by a Search field in rule file: 
        search /search/script/pathname
This script is called with URL pathname of the document from which the query was issued from, in PATH_INFO environment variable, and absolute (translated) document pathname in PATH_TRANSLATED environment variable. Keyword part of the URL is (undecoded) in QUERY_STRING environment variable, and also decoded as command line parameters, one in each of argv[1], argv[2], ...

Search script must conform to CGI/1.0 rules, that is, it has to output either a Location: field, or start its output with: 

        Content-Type: text/html
followed by a blank line. (The Content-Type can, of course, be also other than text/html -- this was just an example.

Binding Suffixes to MIME Content-Types

 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. CERN httpd has an extensive set of predefined suffixes, so usually you don't need to specify any.

The syntax is: 

        AddType .suffix  representation  encoding [quality]
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.

Examples

        AddType .html text/html              8bit     1.0
        AddType .text text/plain             7bit     0.9
        AddType .ps   application/postscript 8bit     1.0
        AddType *.*   application/binary     binary   0.1
        AddType *     text/plain             7bit

Historical Note (Suffix Directive)

AddType was previously called Suffix. The old name is still understood, but may be misleading since suffixes are also used to determine Content-Encoding and language. Always use AddType instead.

Binding Suffixes to MIME Content-Endocings

 Suffixes are also used to determine the Content-Encoding of a file (.Z suffix for x-compressed, for example). Syntax is: 
        AddEncoding .suffix  encoding

Example

        AddEncoding .Z  x-compressed

Multilanguage Support

 Multilanguage support is also built on using suffixes to determine the language of a document. Suffix is bound to a language by AddLanguage rule (.en suffix for english, for example). Syntax is: 
        AddLanguage .suffix  encoding

Examples

        AddLanguage .en  en
        AddLanguage .uk  en_UK

User-Supported Directories

User-supported directories, URLs of form /~username, are enabled by UserDir directive: 
        UserDir dir-name
The dir-name argument is the directory in each user's home directory to be exported, for example WWW or Web.

Meta-Information

It is possible to tell httpd to add meta-information to response. Meta-information is stored in a directory specified by MetaDir directive, under the same directory as the file being retrieved: 
        MetaDir  dir-name
Meta-information is stored in a file with the same name as the actual document, but appended with a suffix specified via MetaSuffix directive: 
        MetaSuffix  .suffix
Meta-information files contain RFC822-style headers.

Suppressing Log Entries For Certain Hosts/Domains

It's not always necessary to collect log information of accesses made by local hosts. The NoLog directive can be used to prevent log entry being made for hosts matching a given IP number or host name template: 
        NoLog  template

Examples

        NoLog 128.141.*.*
        NoLog *.cern.ch
        NoLog *.ch  *.fr  *.it

Enabling and Disabling HTTP Methods

You can enable/disable methods that you do/don't want your server to accept: 
        Enable  method
        Disable method
By default GET, HEAD and POST are enabled, and the rest are disabled.

Examples

        Enable POST
        Disable DELETE
httpd@info.cern.ch