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
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`. For
-example, then, if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the
-directories `/usr/local/etc`, `/etc` and `/usr/etc` are searched for
-`dirplex.rc`, in that order. Only the first file found is used, should
-there exist several.
+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.
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'...]::
+
+ Read the named files and act as if their contents stood in
+ place of the *include* stanza. A 'FILENAME' may be a glob
+ pattern, in which case all matching files are used, sorted by
+ their filenames. If a 'FILENAME' is a relative path, it is
+ treated relative to the directory containing the file from
+ which the *include* stanza was read, even if the inclusion has
+ been nested. Inclusions may be nested to any level.
*index-file* ['FILENAME'...]::
*fchild* 'NAME'::
Declares a named, transient request handler (see *ashd*(7) for
- a more detailed description of persistent handlers). It must
+ a more detailed description of transient handlers). It must
contain exactly one follow-up line, *exec* 'PROGRAM'
['ARGS'...], specifying the program to execute and the
arguments to pass it. In addition to the specified arguments,
the HTTP method, raw URL and the rest string will be appended
- added as described in *ashd*(7). If given in a `.htrc` file,
- the program will be started in the same directory as the
- `.htrc` file itself.
+ as described in *ashd*(7). If given in a `.htrc` file, the
+ program will be started in the same directory as the `.htrc`
+ file itself.
*match* [*directory*]::
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.
+ follow-up lines. Note that the `X-Ash-File` header is not
+ added to requests passed via *capture* directives.
MATCHING
--------
*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*::
Matches if and only if no *match* stanza without a *default*
- rule has matched.
+ rule matches (in any configuration file).
*local*::
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
-------------
-Any of the following cases will result in a 404 response being sent to
-the client.
+A HTTP 404 response is sent to the client if
- * Failure of the mapping procedure to find a matching physical file.
- * Presence of a path element during mapping that begins with a dot.
- * A path element which, after URL unescaping, contains slashes.
- * The mapping procedure finding a file which is neither a directory
- nor a regular file.
- * Presence of a non-final but empty path element during mapping.
- * A physical file having been found which is not being matched by any
+ * The mapping procedure fails to find a matching physical file;
+ * 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 (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.
-*dirplex* will send a built-in 404 response by default, but any
+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.
The built-in `.notfound` handler can also be used in *match* or
-*capture* stanzas.
+*capture* stanzas (for example, to restrict access to certain files or
+directories).
EXAMPLES
--------
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
*callcgi*(1) program.
--------
+# To use plain CGI, which uses more resources per handled request,
+# but less static resources:
fchild php
exec callcgi -p php-cgi
+
+# To use FastCGI, which keeps PHP running at all times, but uses less
+# resources per handled request:
+child php
+ exec callfcgi multifscgi 5 php-cgi
+
match
filename *.php
handler php
fork htls
--------
-If you want an entire directory to be dedicated to some external SCGI
-script engine, you can use the *callscgi*(1) program to serve it as
-follows. 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.
+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 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