X-Git-Url: http://www.dolda2000.com/gitweb/?p=ashd.git;a=blobdiff_plain;f=doc%2Fdirplex.doc;h=fb4b7e71d40021d17b6bc5067ef097c1b52e5ee6;hp=7e9ab383af7bad9e2f5df1e62372e157c9d0eb3a;hb=eb968b932571cac89ca65ce6d522af369757e17f;hpb=2f9428608e54bb015722c76e64cf9faf1df8b19e diff --git a/doc/dirplex.doc b/doc/dirplex.doc index 7e9ab38..fb4b7e7 100644 --- a/doc/dirplex.doc +++ b/doc/dirplex.doc @@ -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 -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 @@ -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. +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 -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 @@ -123,6 +128,16 @@ treated as comments and ignored. 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 @@ -152,14 +167,14 @@ The follow configuration directives are recognized: *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*]:: @@ -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 - follow-up lines. + follow-up lines. Note that the `X-Ash-File` header is not + added to requests passed via *capture* directives. MATCHING -------- @@ -217,7 +233,7 @@ The following rules are recognized: *default*:: Matches if and only if no *match* stanza without a *default* - rule has matched. + rule matches (in any configuration file). *local*:: @@ -245,8 +261,45 @@ following actions are recognized: 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 -------- @@ -254,9 +307,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 + xset content-type text/html + handler send -------- Assuming the PHP CGI interpreter is installed on the system, PHP @@ -264,8 +321,16 @@ scripts can be used with the following configuration, using the *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 @@ -280,11 +345,12 @@ match directory 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