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