X-Git-Url: http://dolda2000.com/gitweb/?a=blobdiff_plain;f=doc%2Fdirplex.doc;h=3737e24f176cce543308210e0aa63c42b3dbebb8;hb=dc38734591c5e26403b608078ce41b67a012d7f2;hp=362a5d784a87a18abb5571b662f405c6c22978f9;hpb=16c2bec346ae486bd09d0b18ab276b4c89005cad;p=ashd.git diff --git a/doc/dirplex.doc b/doc/dirplex.doc index 362a5d7..3737e24 100644 --- a/doc/dirplex.doc +++ b/doc/dirplex.doc @@ -49,16 +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 -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 @@ -67,7 +71,7 @@ element. If there is such a file, it is considered the result of the 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, @@ -81,12 +85,13 @@ 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/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 @@ -122,7 +127,7 @@ as part of the word. Empty lines are ignored, and lines whose first 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'...]:: @@ -172,23 +177,26 @@ The follow configuration directives are recognized: 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 -------- @@ -202,10 +210,13 @@ ignored. 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. @@ -220,11 +231,13 @@ The following rules are recognized: *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*:: @@ -257,6 +270,22 @@ following actions are recognized: 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 ------------- @@ -266,16 +295,28 @@ A HTTP 404 response is sent to the client if * 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 @@ -287,9 +328,13 @@ 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 @@ -324,9 +369,9 @@ match directory 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