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 If the path element names a directory in the current directory, the
  59 procedure continues in that directory. If it names a file, that file
  60 is considered the result of the mapping (even if the rest string has
  61 not been exhausted yet).
  62
  63 If the path element does not name anything in the directory under
  64 consideration, but contains no dots, then the directory is searched
  65 for a file whose name before the first dot matches the path
  66 element. If there is such a file, it is considered the result of the
  67 mapping.
  68
  69 If the result of the mapping procedure is a directory, it is checked
  70 for the presence of a filed named by the *index-file* configuration
  71 directive (see CONFIGURATION below). If there is such a file, it is
  72 considered the final result instead of the directory itself. If the
  73 index file name contains no dots and there is no exact match, then,
  74 again, the directory is searched for a file whose name before the
  75 first dot matches the index file name.
  76
  77 See also 404 RESPONSES below.
  78
  79 CONFIGURATION
  80 -------------
  81
  82 Configuration in *dirplex* comes from several sources. When *dirplex*
  83 starts, unless the *-N* option is given, it tries to find a global
  84 configuration file named `dirplex.rc`. It looks in all directories
  85 named by the *PATH* environment variable, appended with
  86 `../etc/ashd`. For example, then, if *PATH* is
  87 `/usr/local/bin:/bin:/usr/bin`, the directories `/usr/local/etc/ashd`,
  88 `/etc/ashd` and `/usr/etc/ashd` are searched for `dirplex.rc`, in that
  89 order. Only the first file found is used, should there exist several.
  90
  91 If the *-c* option is given to *dirplex*, it too specifies a
  92 configuration file to load. If the name given contains any slashes, it
  93 is opened by that exact name. Otherwise, it is searched for in the
  94 same manner as the global configuration file.
  95
  96 In addition, all directories traversed by *dirplex* when mapping a URL
  97 into a physical file may contain a file called `.htrc`, which may
  98 specify extra configuration options for all files in and beneath that
  99 directory.
 100
 101 `.htrc` files are checked periodically and reread if changed. The
 102 global configuration file and any file named by the *-c* option,
 103 however, are never reexamined.
 104
 105 When using the configuration files for deciding what to do with a
 106 found file, they are examined in order of their "distance" from that
 107 file. `.htrc` files found in the directory or directories containing
 108 the file are considered "closest" to the file under consideration,
 109 followed by any configuration file named by the *-c* option, followed
 110 by the global configuration file.
 111
 112 Each configuration file is a sequence of configuration stanzas, each
 113 stanza being an unindented starting line, followed by zero or more
 114 indented follow-up lines adding options to the stanza. The starting
 115 line of a stanza is referred to as a "configuration directive"
 116 below. Each line is a sequence of whitespace-separated words. A word
 117 may contain whitespace if such whitespace is escaped, either by
 118 enclosing the word in double quotes, or by escaping individual
 119 whitespace characters with a preceding backslash. Backslash quoting
 120 may also be used to treat double quotes or another backslash literally
 121 as part of the word. Empty lines are ignored, and lines whose first
 122 character after leading whitespace is a hash character (`#`) are
 123 treated as comments and ignored.
 124
 125 The follow configuration directives are recognized:
 126
 127 *include* ['FILENAME'...]::
 128
 129         Read the named files and act as if their contents stood in
 130         place of the *include* stanza. A 'FILENAME' may be a glob
 131         pattern, in which case all matching files are used, sorted by
 132         their filenames. If a 'FILENAME' is a relative path, it is
 133         treated relative to the directory containing the file from
 134         which the *include* stanza was read, even if the inclusion has
 135         been nested. Inclusions may be nested to any level.
 136
 137 *index-file* ['FILENAME'...]::
 138
 139         The given 'FILENAMEs' are used for finding index files (see
 140         URL-TO-FILE MAPPING above). Specifying *index-file* overrides
 141         entirely any previous specification in a more distant
 142         configuration file, rather than adding to it. Zero 'FILENAMEs'
 143         may be given to turn off index file searching completely. The
 144         *index-file* directive accepts no follow-up lines.
 145
 146 *child* 'NAME'::
 147
 148         Declares a named, persistent request handler (see *ashd*(7)
 149         for a more detailed description of persistent handlers). It
 150         must contain exactly one follow-up line, *exec* 'PROGRAM'
 151         ['ARGS'...], specifying the program to execute and the
 152         arguments to pass it. If given in a `.htrc` file, the program
 153         will be started in the same directory as the `.htrc` file
 154         itself. The *child* stanza itself serves as the identity of
 155         the forked process -- only one child process will be forked
 156         per stanza, and if that child process exits, it will be
 157         restarted the next time the stanza would be used. If a `.htrc`
 158         file containing *child* stanzas is reloaded, any currently
 159         running children are reused for *child* stanzas in the new
 160         file with matching names (even if the *exec* line has
 161         changed).
 162
 163 *fchild* 'NAME'::
 164
 165         Declares a named, transient request handler (see *ashd*(7) for
 166         a more detailed description of transient handlers). It must
 167         contain exactly one follow-up line, *exec* 'PROGRAM'
 168         ['ARGS'...], specifying the program to execute and the
 169         arguments to pass it. In addition to the specified arguments,
 170         the HTTP method, raw URL and the rest string will be appended
 171         as described in *ashd*(7). If given in a `.htrc` file, the
 172         program will be started in the same directory as the `.htrc`
 173         file itself.
 174
 175 *match* [*directory*]::
 176
 177         Specifies a filename pattern-matching rule. The
 178         pattern-matching procedure and the follow-up lines accepted by
 179         this stanza are described below, under MATCHING.
 180
 181 *capture* 'HANDLER'::
 182
 183         Only meaningful in `.htrc` files. If a *capture* directive is
 184         specified, then the URL-to-file mapping procedure as described
 185         above is aborted as soon as the directory containing the
 186         `.htrc` file is encountered. The request is passed, with any
 187         remaining rest string, to the specified 'HANDLER', which must
 188         by a named request handler specified either in the same
 189         `.htrc` file or elsewhere. The *capture* directive accepts no
 190         follow-up lines. Note that the `X-Ash-File` header is not
 191         added to requests passed via *capture* directives.
 192
 193 MATCHING
 194 --------
 195
 196 When a file or directory has been found by the mapping procedure (see
 197 URL-TO-FILE MAPPING above), the name of the physical file is examined
 198 to determine a request handler to pass the request to. Note that only
 199 the physical file name is ever considered; any logical request
 200 parameters such as the request URL or the rest string are entirely
 201 ignored.
 202
 203 To match a file, any *match* stanzas specified by any `.htrc` file or
 204 in the global configuration files are searched in order of their
 205 "distance" (see CONFIGURATION above) from the actual file. If it is a
 206 directory which is being considered, only *match* stanzas with the
 207 *directory* parameter are considered; otherwise, if it is a file, only
 208 *match* stanzas without the *directory* parameter are considered.
 209
 210 A *match* stanza must contain at least one follow-up line specifying
 211 match rules. All rules must match for the stanza as a whole to match.
 212 The following rules are recognized:
 213
 214 *filename* 'PATTERN'...::
 215
 216         Matches if the name of the file under consideration matches
 217         any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
 218         pattern, such as `*.php`. See *fnmatch*(3) for more
 219         information.
 220
 221 *pathname* 'PATTERN'...::
 222
 223         Matches if the entire path (relative as considered from the
 224         root directory being served) of the file under consideration
 225         matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
 226         pattern, except that slashes are not matched by wildcards. See
 227         *fnmatch*(3) for more information.
 228
 229 *default*::
 230
 231         Matches if and only if no *match* stanza without a *default*
 232         rule matches (in any configuration file).
 233
 234 *local*::
 235
 236         Valid only in `.htrc` files, *local* matches if and only if
 237         the file under consideration resides in the same directory as
 238         the containing `.htrc` file.
 239
 240 In addition to the rules, a *match* stanza must contain exactly one
 241 follow-up line specifying the action to take if it matches. The
 242 following actions are recognized:
 243
 244 *handler* 'HANDLER'::
 245
 246         'HANDLER' must be a named handler (see CONFIGURATION
 247         above). The named handler is searched for not only in the same
 248         configuration file as the *match* stanza, but in all
 249         configuration files that are valid for the file under
 250         consideration, in order of distance. As such, a more deeply
 251         nested `.htrc` file may override the specified handler without
 252         having to specify any new *match* stanzas.
 253
 254 *fork* 'PROGRAM' ['ARGS'...]::
 255
 256         Run a transient handler for this file, as if it were specified
 257         by a *fchild* stanza. This action exists mostly for
 258         convenience.
 259
 260 404 RESPONSES
 261 -------------
 262
 263 A HTTP 404 response is sent to the client if
 264
 265  * The mapping procedure fails to find a matching physical file;
 266  * A path element is encountered during mapping which, after URL
 267    unescaping, either begins with a dot or contains slashes;
 268  * The mapping procedure finds a file which is neither a directory nor
 269    a regular file;
 270  * An empty, non-final path element is encountered during mapping; or
 271  * The mapping procedure results in a file which is not matched by any
 272    *match* stanza.
 273
 274 By default, *dirplex* will send a built-in 404 response, but any
 275 `.htrc` file or global configuration may define a request handler
 276 named `.notfound` to customize the behavior. Note that, unlike
 277 successful requests, such a handler will not be passed the
 278 `X-Ash-File` header.
 279
 280 The built-in `.notfound` handler can also be used in *match* or
 281 *capture* stanzas (for example, to restrict access to certain files or
 282 directories).
 283
 284 EXAMPLES
 285 --------
 286
 287 The *sendfile*(1) program can be used to serve HTML files as follows.
 288
 289 --------
 290 match
 291   filename *.html
 292   fork sendfile -c text/html
 293 --------
 294
 295 Assuming the PHP CGI interpreter is installed on the system, PHP
 296 scripts can be used with the following configuration, using the
 297 *callcgi*(1) program.
 298
 299 --------
 300 # To use plain CGI, which uses more resources per handled request,
 301 # but less static resources:
 302 fchild php
 303   exec callcgi -p php-cgi
 304
 305 # To use FastCGI, which keeps PHP running at all times, but uses less
 306 # resources per handled request:
 307 child php
 308   exec callfcgi multifscgi 5 php-cgi
 309
 310 match
 311   filename *.php
 312   handler php
 313 --------
 314
 315 If there is a directory without an index file, a file listing can be
 316 automatically generated by the *htls*(1) program as follows.
 317
 318 --------
 319 match directory
 320   default
 321   fork htls
 322 --------
 323
 324 The following configuration can be placed in a `.htrc` file in order
 325 to dedicate the directory containing that file to some external SCGI
 326 script engine. Note that *callscgi*, and therefore the script engine
 327 itself, is started in the directory itself, so that arbitrary code
 328 modules or data files can be put directly in that directory and easily
 329 found.
 330
 331 --------
 332 child foo
 333   exec callscgi scgi-wsgi -p . foo
 334
 335 capture foo
 336 --------
 337
 338 AUTHOR
 339 ------
 340 Fredrik Tolf <fredrik@dolda2000.com>
 341
 342 SEE ALSO
 343 --------
 344 *ashd*(7)