looking in one single physical directory, starting with 'DIR'. For
each step, a path element is stripped off the beginning of the rest
string and examined, the path element being either the leading part of
-the rest string up until the first slash, or the entire rest string if
-it contains no slashes. If the rest string is empty, the directory
-being examined is considered the result of the mapping. Otherwise, any
-escape sequences in the path element under consideration are unescaped
-before examining it.
+the rest string up until (but not including) the first slash, or the
+entire rest string if it contains no slashes. If the rest string is
+empty, the directory being examined is considered the result of the
+mapping. Otherwise, any escape sequences in the path element under
+consideration are unescaped before examining it.
If the path element names a directory in the current directory, the
-procedure continues in that directory. If it names a file, that file
-is considered the result of the mapping (even if the rest string has
-not been exhausted yet).
+procedure continues in that directory, unless there is nothing left of
+the rest string, in which case *dirplex* responds with a HTTP 301
+redirect to the same URL, but ending with a slash. Otherwise, the
+remaining rest string begins with a slash, which is stripped off
+before continuing. If the path element names a file, that file is
+considered the result of the mapping (even if the rest string has not
+been exhausted yet).
If the path element does not name anything in the directory under
consideration, but contains no dots, then the directory is searched
mapping.
If the result of the mapping procedure is a directory, it is checked
-for the presence of a filed named by the *index-file* configuration
+for the presence of a file named by the *index-file* configuration
directive (see CONFIGURATION below). If there is such a file, it is
considered the final result instead of the directory itself. If the
index file name contains no dots and there is no exact match, then,
Configuration in *dirplex* comes from several sources. When *dirplex*
starts, unless the *-N* option is given, it tries to find a global
-configuration file named `dirplex.rc`. It looks in all directories
-named by the *PATH* environment variable, appended with
-`../etc/ashd`. For example, then, if *PATH* is
-`/usr/local/bin:/bin:/usr/bin`, the directories `/usr/local/etc/ashd`,
-`/etc/ashd` and `/usr/etc/ashd` are searched for `dirplex.rc`, in that
-order. Only the first file found is used, should there exist several.
+configuration file named `dirplex.rc`. It looks in `$HOME/.ashd/etc`,
+and then in all directories named by the *PATH* environment variable,
+appended with `../etc/ashd`. For example, then, if *PATH* is
+`/usr/local/bin:/bin:/usr/bin`, the directories `$HOME/.ashd/etc`,
+`/usr/local/etc/ashd`, `/etc/ashd` and `/usr/etc/ashd` are searched
+for `dirplex.rc`, in that order. Only the first file found is used,
+should there exist several.
If the *-c* option is given to *dirplex*, it too specifies a
configuration file to load. If the name given contains any slashes, it
character after leading whitespace is a hash character (`#`) are
treated as comments and ignored.
-The follow configuration directives are recognized:
+The following configuration directives are recognized:
*include* ['FILENAME'...]::
program will be started in the same directory as the `.htrc`
file itself.
-*match* [*directory*]::
+*match* ['TYPE']::
Specifies a filename pattern-matching rule. The
pattern-matching procedure and the follow-up lines accepted by
this stanza are described below, under MATCHING.
-*capture* 'HANDLER'::
+*capture* 'HANDLER' ['FLAGS']::
Only meaningful in `.htrc` files. If a *capture* directive is
specified, then the URL-to-file mapping procedure as described
above is aborted as soon as the directory containing the
`.htrc` file is encountered. The request is passed, with any
remaining rest string, to the specified 'HANDLER', which must
- by a named request handler specified either in the same
+ be a named request handler specified either in the same
`.htrc` file or elsewhere. The *capture* directive accepts no
follow-up lines. Note that the `X-Ash-File` header is not
- added to requests passed via *capture* directives.
+ added to requests passed via *capture* directives. Normally,
+ *capture* directives will be ignored if they appear in the
+ root directory that *dirplex* serves, but not if 'FLAGS'
+ contain the character `D`.
MATCHING
--------
To match a file, any *match* stanzas specified by any `.htrc` file or
in the global configuration files are searched in order of their
-"distance" (see CONFIGURATION above) from the actual file. If it is a
-directory which is being considered, only *match* stanzas with the
-*directory* parameter are considered; otherwise, if it is a file, only
-*match* stanzas without the *directory* parameter are considered.
+"distance" (see CONFIGURATION above) from the actual file. Which
+*match* stanzas are considered depends on the type of the file being
+matched: if an ordinary file is being matched, only *match* stanzas
+without any 'TYPE' parameter are considered, while if it is a
+directory, only those with the 'TYPE' parameter specified as
+*directory* are considered. 'TYPE' can also take the value *notfound*,
+described below under 404 RESPONSES.
A *match* stanza must contain at least one follow-up line specifying
match rules. All rules must match for the stanza as a whole to match.
*pathname* 'PATTERN'...::
- Matches if the entire path (relative as considered from the
- root directory being served) of the file under consideration
+ Matches if the entire path of the file under consideration
matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
pattern, except that slashes are not matched by wildcards. See
- *fnmatch*(3) for more information.
+ *fnmatch*(3) for more information. If a *pathname* rule is
+ specified in a `.htrc` file, the path will be examined as
+ relative to the directory containing the `.htrc` file, rather
+ than to the root directory being served.
*default*::
by a *fchild* stanza. This action exists mostly for
convenience.
+A *match* stanza may also contain any number of the following,
+optional directives:
+
+*set* 'HEADER' 'VALUE'::
+
+ If the *match* stanza is selected as the match for a file, the
+ named HTTP 'HEADER' in the request is set to 'VALUE' before
+ passing the request on to the specified handler.
+
+*xset* 'HEADER' 'VALUE'::
+
+ *xset* does exactly the same thing as *set*, except that
+ 'HEADER' is automatically prepended with the `X-Ash-`
+ prefix. The intention is only to make configuration files
+ look nicer in this very common case.
+
404 RESPONSES
-------------
* A path element is encountered during mapping which, after URL
unescaping, either begins with a dot or contains slashes;
* The mapping procedure finds a file which is neither a directory nor
- a regular file;
+ a regular file (nor a symbolic link to any of the same);
* An empty, non-final path element is encountered during mapping; or
* The mapping procedure results in a file which is not matched by any
*match* stanza.
-By default, *dirplex* will send a built-in 404 response, but any
-`.htrc` file or global configuration may define a request handler
-named `.notfound` to customize the behavior. Note that, unlike
-successful requests, such a handler will not be passed the
-`X-Ash-File` header.
+By default, *dirplex* will send a built-in 404 response, but there are
+two ways to customize the response:
+
+First, *match* stanzas with the type *notfound* will be matched
+against any request that would result in a 404 error. The filename for
+such matching is that of the last succesfully found component, which
+may be a directory, for example in case a name component could not be
+found in the real filesystem; or a file, for example in case a file
+was found, but not matched by any *match* stanzas.
+
+Otherwise, any request that would result in a 404 response but is
+matched by no *notfound* stanza is instead passed to a default handler
+named `.notfound`, which is handled internally in *dirplex* by
+default, but may be overridden just as any other handler may be in a
+`.htrc` file or by global configuration. Note, however, that any
+request not matched by a *notfound* stanza will not have the
+`X-Ash-File` header added to it.
The built-in `.notfound` handler can also be used in *match* or
*capture* stanzas (for example, to restrict access to certain files or
The *sendfile*(1) program can be used to serve HTML files as follows.
--------
+fchild send
+ exec sendfile
+
match
- filename *.html
- fork sendfile -c text/html
+ filename *.html *.htm
+ xset content-type text/html
+ handler send
--------
Assuming the PHP CGI interpreter is installed on the system, PHP
The following configuration can be placed in a `.htrc` file in order
to dedicate the directory containing that file to some external SCGI
script engine. Note that *callscgi*, and therefore the script engine
-itself, is started in the directory itself, so that arbitrary code
-modules or data files can be put directly in that directory and easily
-found.
+itself, is started in the same directory, so that arbitrary code
+modules or data files can be put directly in that directory and be
+easily found.
--------
child foo