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 .
See also: example rule files , Old
format for software before 2.0 ,
Setting up gateways , Firewall gateways
.
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.
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
.
See also the full
description of protect
and defprot.
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