python: Added PDM support in scgi-wsgi{,3}.
[ashd.git] / 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' ['FLAGS']::
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.  If 'FLAGS'
196         contain the character `R`, this *capture* directive will be
197         ignored if it is in the root directory that *dirplex* serves.
198
199 MATCHING
200 --------
201
202 When a file or directory has been found by the mapping procedure (see
203 URL-TO-FILE MAPPING above), the name of the physical file is examined
204 to determine a request handler to pass the request to. Note that only
205 the physical file name is ever considered; any logical request
206 parameters such as the request URL or the rest string are entirely
207 ignored.
208
209 To match a file, any *match* stanzas specified by any `.htrc` file or
210 in the global configuration files are searched in order of their
211 "distance" (see CONFIGURATION above) from the actual file. If it is a
212 directory which is being considered, only *match* stanzas with the
213 *directory* parameter are considered; otherwise, if it is a file, only
214 *match* stanzas without the *directory* parameter are considered.
215
216 A *match* stanza must contain at least one follow-up line specifying
217 match rules. All rules must match for the stanza as a whole to match.
218 The following rules are recognized:
219
220 *filename* 'PATTERN'...::
221
222         Matches if the name of the file under consideration matches
223         any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
224         pattern, such as `*.php`. See *fnmatch*(3) for more
225         information.
226
227 *pathname* 'PATTERN'...::
228
229         Matches if the entire path of the file under consideration
230         matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
231         pattern, except that slashes are not matched by wildcards. See
232         *fnmatch*(3) for more information. If a *pathname* rule is
233         specified in a `.htrc` file, the path will be examined as
234         relative to the directory containing the `.htrc` file, rather
235         than to the root directory being served.
236
237 *default*::
238
239         Matches if and only if no *match* stanza without a *default*
240         rule matches (in any configuration file).
241
242 *local*::
243
244         Valid only in `.htrc` files, *local* matches if and only if
245         the file under consideration resides in the same directory as
246         the containing `.htrc` file.
247
248 In addition to the rules, a *match* stanza must contain exactly one
249 follow-up line specifying the action to take if it matches. The
250 following actions are recognized:
251
252 *handler* 'HANDLER'::
253
254         'HANDLER' must be a named handler (see CONFIGURATION
255         above). The named handler is searched for not only in the same
256         configuration file as the *match* stanza, but in all
257         configuration files that are valid for the file under
258         consideration, in order of distance. As such, a more deeply
259         nested `.htrc` file may override the specified handler without
260         having to specify any new *match* stanzas.
261
262 *fork* 'PROGRAM' ['ARGS'...]::
263
264         Run a transient handler for this file, as if it were specified
265         by a *fchild* stanza. This action exists mostly for
266         convenience.
267
268 A *match* stanza may also contain any number of the following,
269 optional directives:
270
271 *set* 'HEADER' 'VALUE'::
272
273         If the *match* stanza is selected as the match for a file, the
274         named HTTP 'HEADER' in the request is set to 'VALUE' before
275         passing the request on to the specified handler.
276
277 *xset* 'HEADER' 'VALUE'::
278
279         *xset* does exactly the same thing as *set*, except that
280          'HEADER' is automatically prepended with the `X-Ash-`
281          prefix. The intention is only to make configuration files
282          look nicer in this very common case.
283
284 404 RESPONSES
285 -------------
286
287 A HTTP 404 response is sent to the client if
288
289  * The mapping procedure fails to find a matching physical file;
290  * A path element is encountered during mapping which, after URL
291    unescaping, either begins with a dot or contains slashes;
292  * The mapping procedure finds a file which is neither a directory nor
293    a regular file (or a symbolic link to any of the same);
294  * An empty, non-final path element is encountered during mapping; or
295  * The mapping procedure results in a file which is not matched by any
296    *match* stanza.
297
298 By default, *dirplex* will send a built-in 404 response, but any
299 `.htrc` file or global configuration may define a request handler
300 named `.notfound` to customize the behavior. Note that, unlike
301 successful requests, such a handler will not be passed the
302 `X-Ash-File` header.
303
304 The built-in `.notfound` handler can also be used in *match* or
305 *capture* stanzas (for example, to restrict access to certain files or
306 directories).
307
308 EXAMPLES
309 --------
310
311 The *sendfile*(1) program can be used to serve HTML files as follows.
312
313 --------
314 fchild send
315   exec sendfile
316
317 match
318   filename *.html *.htm
319   xset content-type text/html
320   handler send
321 --------
322
323 Assuming the PHP CGI interpreter is installed on the system, PHP
324 scripts can be used with the following configuration, using the
325 *callcgi*(1) program.
326
327 --------
328 # To use plain CGI, which uses more resources per handled request,
329 # but less static resources:
330 fchild php
331   exec callcgi -p php-cgi
332
333 # To use FastCGI, which keeps PHP running at all times, but uses less
334 # resources per handled request:
335 child php
336   exec callfcgi multifscgi 5 php-cgi
337
338 match
339   filename *.php
340   handler php
341 --------
342
343 If there is a directory without an index file, a file listing can be
344 automatically generated by the *htls*(1) program as follows.
345
346 --------
347 match directory
348   default
349   fork htls
350 --------
351
352 The following configuration can be placed in a `.htrc` file in order
353 to dedicate the directory containing that file to some external SCGI
354 script engine. Note that *callscgi*, and therefore the script engine
355 itself, is started in the same directory, so that arbitrary code
356 modules or data files can be put directly in that directory and be
357 easily found.
358
359 --------
360 child foo
361   exec callscgi scgi-wsgi -p . foo
362
363 capture foo
364 --------
365
366 AUTHOR
367 ------
368 Fredrik Tolf <fredrik@dolda2000.com>
369
370 SEE ALSO
371 --------
372 *ashd*(7)