doc/dirplex.doc

   1 dirplex(1)
   2 ==========
   3
   4 NAME
   5 ----
   6 dirplex - Physical directory handler for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *dirplex* [*-hN*] [*-c* 'CONFIG'] 'DIR'
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The *dirplex* handler maps URLs into physical files or directories,
  16 and, having found a matching file or directory, it performs various
  17 kinds of pattern-matching against its physical name to determine what
  18 handler to call in order to serve the request. The mapping procedure
  19 and pattern matching are described below.
  20
  21 Having found a handler to serve a file or directory with, *dirplex*
  22 adds the `X-Ash-File` header to the request with a path to the
  23 physical file, before passing the request on to the handler.
  24
  25 *dirplex* is a persistent handler, as defined in *ashd*(7).
  26
  27 OPTIONS
  28 -------
  29
  30 *-h*::
  31
  32         Print a brief help message to standard output and exit.
  33
  34 *-N*::
  35
  36         Do not read the global configuration file `dirplex.rc`.
  37
  38 *-c* 'CONFIG'::
  39
  40         Read an extra configuration file. If 'CONFIG' contains any
  41         slashes, it is opened by that exact name. Otherwise, it is
  42         searched for in the same way as the global configuration file
  43         (see CONFIGURATION below).
  44
  45 URL-TO-FILE MAPPING
  46 -------------------
  47
  48 Mapping URLs into physical files is an iterative procedure, each step
  49 looking in one single physical directory, starting with 'DIR'. For
  50 each step, a path element is stripped off the beginning of the rest
  51 string and examined, the path element being either the leading part of
  52 the rest string up until the first slash, or the entire rest string if
  53 it contains no slashes. If the rest string is empty, the directory
  54 being examined is considered the result of the mapping. Otherwise, any
  55 escape sequences in the path element under consideration are unescaped
  56 before examining it.
  57
  58 Any path element that begins with a dot is considered invalid and
  59 results in a 404 response to the client. If the path element names a
  60 directory in the current directory, the procedure continues in that
  61 directory. If it names a file, that file is considered the result of
  62 the mapping (even if the rest string has not been exhausted yet).
  63
  64 If the path element does not name anything in the directory under
  65 consideration, but contains no dots, then the directory is searched
  66 for a file whose name before the first dot matches the path
  67 element. If there is such a file, it is considered the result of the
  68 mapping.
  69
  70 If the result of the mapping procedure is a directory, it is checked
  71 for the presence of a filed named by the *index-file* configuration
  72 directive (see CONFIGURATION below). If there is such a file, it is
  73 considered the final result instead of the directory itself. If the
  74 index file name contains no dots and there is no exact match, then,
  75 again, the directory is searched for a file whose name before the
  76 first dot matches the index file name.
  77
  78 CONFIGURATION
  79 -------------
  80
  81 Configuration in *dirplex* comes from several sources. When *dirplex*
  82 starts, unless the *-N* option is given, it tries to find a global
  83 configuration file named `dirplex.rc`. It looks in all directories
  84 named by the *PATH* environment variable, appended with `../etc`. For
  85 example, then, if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the
  86 directories `/usr/local/etc`, `/etc` and `/usr/etc` are searched for
  87 `dirplex.rc`, in that order. Only the first file found is used, should
  88 there exist several.
  89
  90 If the *-c* option is given to *dirplex*, it too specifies a
  91 configuration file to load. If the name given contains any slashes, it
  92 is opened by that exact name. Otherwise, it is searched for in the
  93 same manner as the global configuration file.
  94
  95 In addition, all directories traversed by *dirplex* when mapping a URL
  96 into a physical file may contain a file called `.htrc`, which may
  97 specify extra configuration options for all files in and beneath that
  98 directory.
  99
 100 `.htrc` files are checked periodically and reread if changed. The
 101 global configuration file and any file named by the *-c* option,
 102 however, are never reexamined.
 103
 104 When using the configuration files for deciding what to do with a
 105 found file, they are examined in order of their "distance" from that
 106 file. `.htrc` files found in the directory or directories containing
 107 the file are considered "closest" to the file under consideration,
 108 followed by any configuration file named by the *-c* option, followed
 109 by the global configuration file.
 110
 111 Each configuration file is a sequence of configuration stanzas, each
 112 stanza being an unindented starting line, followed by zero or more
 113 indented follow-up lines adding options to the stanza. The starting
 114 line of a stanza is referred to as a "configuration directive"
 115 below. Each line is a sequence of whitespace-separated words. A word
 116 may contain whitespace if such whitespace is escaped, either by
 117 enclosing the word in double quotes, or by escaping individual
 118 whitespace characters with a preceding backslash. Backslash quoting
 119 may also be used to treat double quotes or another backslash literally
 120 as part of the word. Empty lines are ignored, and lines whose first
 121 character after leading whitespace is a hash character (`#`) are
 122 treated as comments and ignored.
 123
 124 The follow configuration directives are recognized:
 125
 126 *index-file* ['FILENAME'...]::
 127
 128         The given 'FILENAMEs' are used for finding index files (see
 129         URL-TO-FILE MAPPING above). Specifying *index-file* overrides
 130         entirely any previous specification in a more distant
 131         configuration file, rather than adding to it. Zero 'FILENAMEs'
 132         may be given to turn off index file searching completely. The
 133         *index-file* directive accepts no follow-up lines.
 134
 135 *child* 'NAME'::
 136
 137         Declares a named, persistent request handler (see *ashd*(7)
 138         for a more detailed description of persistent handlers). It
 139         must contain exactly one follow-up line, *exec* 'PROGRAM'
 140         ['ARGS'...], specifying the program to execute and the
 141         arguments to pass it. If given in a `.htrc` file, the program
 142         will be started in the same directory as the `.htrc` file
 143         itself. The *child* stanza itself serves as the identity of
 144         the forked process -- only one child process will be forked
 145         per stanza, and if that child process exits, it will be
 146         restarted the next time the stanza would be used. If a `.htrc`
 147         file containing *child* stanzas is reloaded, any currently
 148         running children are reused for *child* stanzas in the new
 149         file with matching names (even if the *exec* line has
 150         changed).
 151
 152 *fchild* 'NAME'::
 153
 154         Declares a named, transient request handler (see *ashd*(7) for
 155         a more detailed description of persistent handlers). It must
 156         contain exactly one follow-up line, *exec* 'PROGRAM'
 157         ['ARGS'...], specifying the program to execute and the
 158         arguments to pass it. In addition to the specified arguments,
 159         the HTTP method, raw URL and the rest string will be appended
 160         added as described in *ashd*(7). If given in a `.htrc` file,
 161         the program will be started in the same directory as the
 162         `.htrc` file itself.
 163
 164 *match* [*directory*]::
 165
 166         Specifies a filename pattern-matching rule. The
 167         pattern-matching procedure and the follow-up lines accepted by
 168         this stanza are described below, under MATCHING.
 169
 170 *capture* 'HANDLER'::
 171
 172         Only meaningful in `.htrc` files. If a *capture* directive is
 173         specified, then the URL-to-file mapping procedure as described
 174         above is aborted as soon as the directory containing the
 175         `.htrc` file is encountered. The request is passed, with any
 176         remaining rest string, to the specified 'HANDLER', which must
 177         by a named request handler specified either in the same
 178         `.htrc` file or elsewhere. The *capture* directive accepts no
 179         follow-up lines.
 180
 181 MATCHING
 182 --------
 183
 184 When a file or directory has been found by the mapping procedure (see
 185 URL-TO-FILE MAPPING above), the name of the physical file is examined
 186 to determine a request handler to pass the request to. Note that only
 187 the physical file name is ever considered; any logical request
 188 parameters such as the request URL or the rest string are entirely
 189 ignored.
 190
 191 To match a file, any *match* stanzas specified by any `.htrc` file or
 192 in the global configuration files are searched in order of their
 193 "distance" (see CONFIGURATION above) from the actual file. If it is a
 194 directory which is being considered, only *match* stanzas with the
 195 *directory* parameter are considered; otherwise, if it is a file, only
 196 *match* stanzas without the *directory* parameter are considered.
 197
 198 A *match* stanza must contain at least one follow-up line specifying
 199 match rules. All rules must match for the stanza as a whole to match.
 200 The following rules are recognized:
 201
 202 *filename* 'PATTERN'...::
 203
 204         Matches if the name of the file under consideration matches
 205         any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
 206         pattern, such as `*.php`. See *fnmatch*(3) for more
 207         information.
 208
 209 *pathname* 'PATTERN'...::
 210
 211         Matches if the entire path (relative as considered from the
 212         root directory being served) of the file under consideration
 213         matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
 214         pattern, except that slashes are not matched by wildcards. See
 215         *fnmatch*(3) for more information.
 216
 217 *default*::
 218
 219         Matches if and only if no *match* stanza without a *default*
 220         rule has matched.
 221
 222 In addition to the rules, a *match* stanza must contain exactly one
 223 follow-up line specifying the action to take if it matches. The
 224 following actions are recognized:
 225
 226 *handler* 'HANDLER'::
 227
 228         'HANDLER' must be a named handler (see CONFIGURATION
 229         above). The named handler is searched for not only in the same
 230         configuration file as the *match* stanza, but in all
 231         configuration files that are valid for the file under
 232         consideration, in order of distance. As such, a more deeply
 233         nested `.htrc` file may override the specified handler without
 234         having to specify any new *match* stanzas.
 235
 236 *fork* 'PROGRAM' ['ARGS'...]::
 237
 238         Run a transient handler for this file, as if it were specified
 239         by a *fchild* stanza. This action exists mostly for
 240         convenience.
 241
 242 If no *match* stanza matches, a 404 response is returned to the
 243 client.
 244
 245 EXAMPLES
 246 --------
 247
 248 The *sendfile*(1) program can be used to serve HTML files as follows.
 249
 250 --------
 251 match
 252   filename *.html
 253   fork sendfile -c text/html
 254 --------
 255
 256 Assuming the PHP CGI interpreter is installed on the system, PHP
 257 scripts can be used with the following configuration, using the
 258 *callcgi*(1) program.
 259
 260 --------
 261 fchild php
 262   exec callcgi -p php-cgi
 263 match
 264   filename *.php
 265   handler php
 266 --------
 267
 268 If there is a directory without an index file, a file listing can be
 269 automatically generated by the *htls*(1) program as follows.
 270
 271 --------
 272 match directory
 273   default
 274   fork htls
 275 --------
 276
 277 If you want an entire directory to be dedicated to some external SCGI
 278 script engine, you can use the *callscgi*(1) program to serve it as
 279 follows. Note that *callscgi*, and therefore the script engine itself,
 280 is started in the directory itself, so that arbitrary code modules or
 281 data files can be put directly in that directory and easily found.
 282
 283 --------
 284 child foo
 285   exec callscgi scgi-wsgi -p . foo
 286
 287 capture foo
 288 --------
 289
 290 AUTHOR
 291 ------
 292 Fredrik Tolf <fredrik@dolda2000.com>
 293
 294 SEE ALSO
 295 --------
 296 *ashd*(7)