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