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*::
*xset* 'HEADER' 'VALUE'::
- *xset* does exactly the same thing as *set*, except the
+ *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.
* 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 (or 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
Dolda2000 GitWeb / ashd.git / blobdiff