doc: Use `xset content-type' for the dirplex sendfile example.

[ashd.git] / doc / dirplex.doc

diff --git a/doc/dirplex.doc b/doc/dirplex.doc
index 9d4583d..fb4b7e7 100644 (file)
--- a/doc/dirplex.doc
+++ b/doc/dirplex.doc
@@ -29,7 +29,7 @@ OPTIONS
 
 *-h*::
 
 
 *-h*::
 

-       Display a brief help message to standard output and exit.
+       Print a brief help message to standard output and exit.

 
 *-N*::
 
 
 *-N*::
 


@@ -49,17 +49,20 @@ Mapping URLs into physical files is an iterative procedure, each step
 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
 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.
-
-Any path element that begins with a dot is considered invalid and
-results in a 404 response to the client. 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).
+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, 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
 
 If the path element does not name anything in the directory under
 consideration, but contains no dots, then the directory is searched


@@ -75,17 +78,19 @@ index file name contains no dots and there is no exact match, then,
 again, the directory is searched for a file whose name before the
 first dot matches the index file name.
 
 again, the directory is searched for a file whose name before the
 first dot matches the index file name.
 

+See also 404 RESPONSES below.
+

 CONFIGURATION
 -------------
 
 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
 CONFIGURATION
 -------------
 
 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
 
 If the *-c* option is given to *dirplex*, it too specifies a
 configuration file to load. If the name given contains any slashes, it


@@ -123,6 +128,16 @@ treated as comments and ignored.
 
 The follow configuration directives are recognized:
 
 
 The follow 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'...]::
 
        The given 'FILENAMEs' are used for finding index files (see
 *index-file* ['FILENAME'...]::
 
        The given 'FILENAMEs' are used for finding index files (see


@@ -152,14 +167,14 @@ The follow configuration directives are recognized:
 *fchild* 'NAME'::
 
        Declares a named, transient request handler (see *ashd*(7) for
 *fchild* 'NAME'::
 
        Declares a named, transient request handler (see *ashd*(7) for

-       a more detailed description of persistent handlers). It must
-       contains exactly one follow-up line, *exec* 'PROGRAM'
+       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
        ['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*]::
 
 
 *match* [*directory*]::
 


@@ -176,7 +191,8 @@ The follow configuration directives are recognized:
        remaining rest string, to the specified 'HANDLER', which must
        by a named request handler specified either in the same
        `.htrc` file or elsewhere. The *capture* directive accepts no
        remaining rest string, to the specified 'HANDLER', which must
        by 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
 --------
 
 MATCHING
 --------


@@ -217,7 +233,13 @@ The following rules are recognized:
 *default*::
 
        Matches if and only if no *match* stanza without a *default*
 *default*::
 
        Matches if and only if no *match* stanza without a *default*

-       rule has matched.
+       rule matches (in any configuration file).
+
+*local*::
+
+       Valid only in `.htrc` files, *local* matches if and only if
+       the file under consideration resides in the same directory as
+       the containing `.htrc` file.

 
 In addition to the rules, a *match* stanza must contain exactly one
 follow-up line specifying the action to take if it matches. The
 
 In addition to the rules, a *match* stanza must contain exactly one
 follow-up line specifying the action to take if it matches. The


@@ -239,8 +261,45 @@ following actions are recognized:
        by a *fchild* stanza. This action exists mostly for
        convenience.
 
        by a *fchild* stanza. This action exists mostly for
        convenience.
 

-If no *match* stanza matches, a 404 response is returned to the
-client.
+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 the
+         '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 HTTP 404 response is sent to the client if
+
+ * 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;
+ * 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.
+
+The built-in `.notfound` handler can also be used in *match* or
+*capture* stanzas (for example, to restrict access to certain files or
+directories).

 
 EXAMPLES
 --------
 
 EXAMPLES
 --------


@@ -248,9 +307,13 @@ EXAMPLES
 The *sendfile*(1) program can be used to serve HTML files as follows.
 
 --------
 The *sendfile*(1) program can be used to serve HTML files as follows.
 
 --------

+fchild send
+  exec sendfile
+

 match
   filename *.html
 match
   filename *.html

-  fork sendfile -c text/html
+  xset content-type text/html
+  handler send

 --------
 
 Assuming the PHP CGI interpreter is installed on the system, PHP
 --------
 
 Assuming the PHP CGI interpreter is installed on the system, PHP


@@ -258,8 +321,16 @@ scripts can be used with the following configuration, using the
 *callcgi*(1) program.
 
 --------
 *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
 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
 match
   filename *.php
   handler php


@@ -274,11 +345,12 @@ match directory
   fork htls
 --------
 
   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 directory itself, so that arbitrary code
+modules or data files can be put directly in that directory and easily
+found.

 
 --------
 child foo
 
 --------
 child foo