doc: Added manpage for errlogger.
[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 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 `../etc`. For
86 example, then, if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the
87 directories `/usr/local/etc`, `/etc` and `/usr/etc` are searched for
88 `dirplex.rc`, in that order. Only the first file found is used, should
89 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 *index-file* ['FILENAME'...]::
128
129         The given 'FILENAMEs' are used for finding index files (see
130         URL-TO-FILE MAPPING above). Specifying *index-file* overrides
131         entirely any previous specification in a more distant
132         configuration file, rather than adding to it. Zero 'FILENAMEs'
133         may be given to turn off index file searching completely. The
134         *index-file* directive accepts no follow-up lines.
135
136 *child* 'NAME'::
137
138         Declares a named, persistent request handler (see *ashd*(7)
139         for a more detailed description of persistent handlers). It
140         must contain exactly one follow-up line, *exec* 'PROGRAM'
141         ['ARGS'...], specifying the program to execute and the
142         arguments to pass it. If given in a `.htrc` file, the program
143         will be started in the same directory as the `.htrc` file
144         itself. The *child* stanza itself serves as the identity of
145         the forked process -- only one child process will be forked
146         per stanza, and if that child process exits, it will be
147         restarted the next time the stanza would be used. If a `.htrc`
148         file containing *child* stanzas is reloaded, any currently
149         running children are reused for *child* stanzas in the new
150         file with matching names (even if the *exec* line has
151         changed).
152
153 *fchild* 'NAME'::
154
155         Declares a named, transient request handler (see *ashd*(7) for
156         a more detailed description of persistent handlers). It must
157         contain exactly one follow-up line, *exec* 'PROGRAM'
158         ['ARGS'...], specifying the program to execute and the
159         arguments to pass it. In addition to the specified arguments,
160         the HTTP method, raw URL and the rest string will be appended
161         added as described in *ashd*(7). If given in a `.htrc` file,
162         the program will be started in the same directory as the
163         `.htrc` file itself.
164
165 *match* [*directory*]::
166
167         Specifies a filename pattern-matching rule. The
168         pattern-matching procedure and the follow-up lines accepted by
169         this stanza are described below, under MATCHING.
170
171 *capture* 'HANDLER'::
172
173         Only meaningful in `.htrc` files. If a *capture* directive is
174         specified, then the URL-to-file mapping procedure as described
175         above is aborted as soon as the directory containing the
176         `.htrc` file is encountered. The request is passed, with any
177         remaining rest string, to the specified 'HANDLER', which must
178         by a named request handler specified either in the same
179         `.htrc` file or elsewhere. The *capture* directive accepts no
180         follow-up lines.
181
182 MATCHING
183 --------
184
185 When a file or directory has been found by the mapping procedure (see
186 URL-TO-FILE MAPPING above), the name of the physical file is examined
187 to determine a request handler to pass the request to. Note that only
188 the physical file name is ever considered; any logical request
189 parameters such as the request URL or the rest string are entirely
190 ignored.
191
192 To match a file, any *match* stanzas specified by any `.htrc` file or
193 in the global configuration files are searched in order of their
194 "distance" (see CONFIGURATION above) from the actual file. If it is a
195 directory which is being considered, only *match* stanzas with the
196 *directory* parameter are considered; otherwise, if it is a file, only
197 *match* stanzas without the *directory* parameter are considered.
198
199 A *match* stanza must contain at least one follow-up line specifying
200 match rules. All rules must match for the stanza as a whole to match.
201 The following rules are recognized:
202
203 *filename* 'PATTERN'...::
204
205         Matches if the name of the file under consideration matches
206         any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
207         pattern, such as `*.php`. See *fnmatch*(3) for more
208         information.
209
210 *pathname* 'PATTERN'...::
211
212         Matches if the entire path (relative as considered from the
213         root directory being served) of the file under consideration
214         matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
215         pattern, except that slashes are not matched by wildcards. See
216         *fnmatch*(3) for more information.
217
218 *default*::
219
220         Matches if and only if no *match* stanza without a *default*
221         rule has matched.
222
223 *local*::
224
225         Valid only in `.htrc` files, *local* matches if and only if
226         the file under consideration resides in the same directory as
227         the containing `.htrc` file.
228
229 In addition to the rules, a *match* stanza must contain exactly one
230 follow-up line specifying the action to take if it matches. The
231 following actions are recognized:
232
233 *handler* 'HANDLER'::
234
235         'HANDLER' must be a named handler (see CONFIGURATION
236         above). The named handler is searched for not only in the same
237         configuration file as the *match* stanza, but in all
238         configuration files that are valid for the file under
239         consideration, in order of distance. As such, a more deeply
240         nested `.htrc` file may override the specified handler without
241         having to specify any new *match* stanzas.
242
243 *fork* 'PROGRAM' ['ARGS'...]::
244
245         Run a transient handler for this file, as if it were specified
246         by a *fchild* stanza. This action exists mostly for
247         convenience.
248
249 404 RESPONSES
250 -------------
251
252 Any of the following cases will result in a 404 response being sent to
253 the client.
254
255  * Failure of the mapping procedure to find a matching physical file.
256  * Presence of a path element during mapping that begins with a dot.
257  * A path element which, after URL unescaping, contains slashes.
258  * The mapping procedure finding a file which is neither a directory
259    nor a regular file.
260  * Presence of a non-final but empty path element during mapping.
261  * A physical file having been found which is not being matched by any
262    *match* stanza.
263
264 *dirplex* will send a built-in 404 response by default, but any
265 `.htrc` file or global configuration may define a request handler
266 named `.notfound` to customize the behavior. Note that, unlike
267 successful requests, such a handler will not be passed the
268 `X-Ash-File` header.
269
270 The built-in `.notfound` handler can also be used in *match* or
271 *capture* stanzas.
272
273 EXAMPLES
274 --------
275
276 The *sendfile*(1) program can be used to serve HTML files as follows.
277
278 --------
279 match
280   filename *.html
281   fork sendfile -c text/html
282 --------
283
284 Assuming the PHP CGI interpreter is installed on the system, PHP
285 scripts can be used with the following configuration, using the
286 *callcgi*(1) program.
287
288 --------
289 fchild php
290   exec callcgi -p php-cgi
291 match
292   filename *.php
293   handler php
294 --------
295
296 If there is a directory without an index file, a file listing can be
297 automatically generated by the *htls*(1) program as follows.
298
299 --------
300 match directory
301   default
302   fork htls
303 --------
304
305 If you want an entire directory to be dedicated to some external SCGI
306 script engine, you can use the *callscgi*(1) program to serve it as
307 follows. Note that *callscgi*, and therefore the script engine itself,
308 is started in the directory itself, so that arbitrary code modules or
309 data files can be put directly in that directory and easily found.
310
311 --------
312 child foo
313   exec callscgi scgi-wsgi -p . foo
314
315 capture foo
316 --------
317
318 AUTHOR
319 ------
320 Fredrik Tolf <fredrik@dolda2000.com>
321
322 SEE ALSO
323 --------
324 *ashd*(7)