doc: Fixed markup error.
[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
52the rest string up until the first slash, or the entire rest string if
53it contains no slashes. If the rest string is empty, the directory
54being examined is considered the result of the mapping. Otherwise, any
55escape sequences in the path element under consideration are unescaped
56before examining it.
57
b70b2d4f
FT
58If the path element names a directory in the current directory, the
59procedure continues in that directory. If it names a file, that file
60is considered the result of the mapping (even if the rest string has
61not been exhausted yet).
e7e3e593
FT
62
63If the path element does not name anything in the directory under
64consideration, but contains no dots, then the directory is searched
65for a file whose name before the first dot matches the path
66element. If there is such a file, it is considered the result of the
67mapping.
68
69If the result of the mapping procedure is a directory, it is checked
70for the presence of a filed named by the *index-file* configuration
71directive (see CONFIGURATION below). If there is such a file, it is
72considered the final result instead of the directory itself. If the
73index file name contains no dots and there is no exact match, then,
74again, the directory is searched for a file whose name before the
75first dot matches the index file name.
76
b70b2d4f
FT
77See also 404 RESPONSES below.
78
e7e3e593
FT
79CONFIGURATION
80-------------
81
82Configuration in *dirplex* comes from several sources. When *dirplex*
83starts, unless the *-N* option is given, it tries to find a global
84configuration file named `dirplex.rc`. It looks in all directories
9f974c1f
FT
85named 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
89order. Only the first file found is used, should there exist several.
e7e3e593
FT
90
91If the *-c* option is given to *dirplex*, it too specifies a
92configuration file to load. If the name given contains any slashes, it
93is opened by that exact name. Otherwise, it is searched for in the
94same manner as the global configuration file.
95
96In addition, all directories traversed by *dirplex* when mapping a URL
97into a physical file may contain a file called `.htrc`, which may
98specify extra configuration options for all files in and beneath that
99directory.
100
101`.htrc` files are checked periodically and reread if changed. The
102global configuration file and any file named by the *-c* option,
103however, are never reexamined.
104
105When using the configuration files for deciding what to do with a
106found file, they are examined in order of their "distance" from that
107file. `.htrc` files found in the directory or directories containing
108the file are considered "closest" to the file under consideration,
109followed by any configuration file named by the *-c* option, followed
110by the global configuration file.
111
112Each configuration file is a sequence of configuration stanzas, each
113stanza being an unindented starting line, followed by zero or more
114indented follow-up lines adding options to the stanza. The starting
115line of a stanza is referred to as a "configuration directive"
116below. Each line is a sequence of whitespace-separated words. A word
117may contain whitespace if such whitespace is escaped, either by
118enclosing the word in double quotes, or by escaping individual
119whitespace characters with a preceding backslash. Backslash quoting
120may also be used to treat double quotes or another backslash literally
121as part of the word. Empty lines are ignored, and lines whose first
122character after leading whitespace is a hash character (`#`) are
123treated as comments and ignored.
124
125The follow configuration directives are recognized:
126
aa7e4406
FT
127*include* ['FILENAME'...]::
128
129 Read the 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
e7e3e593
FT
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 persistent handlers). It must
67223ca4 167 contain exactly one follow-up line, *exec* 'PROGRAM'
e7e3e593
FT
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
9f974c1f
FT
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.
e7e3e593
FT
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.
191
192MATCHING
193--------
194
195When a file or directory has been found by the mapping procedure (see
196URL-TO-FILE MAPPING above), the name of the physical file is examined
197to determine a request handler to pass the request to. Note that only
198the physical file name is ever considered; any logical request
199parameters such as the request URL or the rest string are entirely
200ignored.
201
202To match a file, any *match* stanzas specified by any `.htrc` file or
203in the global configuration files are searched in order of their
204"distance" (see CONFIGURATION above) from the actual file. If it is a
205directory which is being considered, only *match* stanzas with the
206*directory* parameter are considered; otherwise, if it is a file, only
207*match* stanzas without the *directory* parameter are considered.
208
209A *match* stanza must contain at least one follow-up line specifying
210match rules. All rules must match for the stanza as a whole to match.
211The following rules are recognized:
212
213*filename* 'PATTERN'...::
214
215 Matches if the name of the file under consideration matches
216 any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
217 pattern, such as `*.php`. See *fnmatch*(3) for more
218 information.
219
220*pathname* 'PATTERN'...::
221
222 Matches if the entire path (relative as considered from the
223 root directory being served) of the file under consideration
224 matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
225 pattern, except that slashes are not matched by wildcards. See
226 *fnmatch*(3) for more information.
227
228*default*::
229
230 Matches if and only if no *match* stanza without a *default*
231 rule has matched.
232
7711283c
FT
233*local*::
234
2f942860
FT
235 Valid only in `.htrc` files, *local* matches if and only if
236 the file under consideration resides in the same directory as
237 the containing `.htrc` file.
7711283c 238
e7e3e593
FT
239In addition to the rules, a *match* stanza must contain exactly one
240follow-up line specifying the action to take if it matches. The
241following actions are recognized:
242
243*handler* 'HANDLER'::
244
245 'HANDLER' must be a named handler (see CONFIGURATION
246 above). The named handler is searched for not only in the same
247 configuration file as the *match* stanza, but in all
248 configuration files that are valid for the file under
249 consideration, in order of distance. As such, a more deeply
250 nested `.htrc` file may override the specified handler without
251 having to specify any new *match* stanzas.
252
253*fork* 'PROGRAM' ['ARGS'...]::
254
255 Run a transient handler for this file, as if it were specified
256 by a *fchild* stanza. This action exists mostly for
257 convenience.
258
b70b2d4f
FT
259404 RESPONSES
260-------------
261
262Any of the following cases will result in a 404 response being sent to
263the client.
264
265 * Failure of the mapping procedure to find a matching physical file.
266 * Presence of a path element during mapping that begins with a dot.
267 * A path element which, after URL unescaping, contains slashes.
268 * The mapping procedure finding a file which is neither a directory
269 nor a regular file.
270 * Presence of a non-final but empty path element during mapping.
271 * A physical file having been found which is not being matched by any
272 *match* stanza.
273
274*dirplex* will send a built-in 404 response by default, but any
275`.htrc` file or global configuration may define a request handler
276named `.notfound` to customize the behavior. Note that, unlike
277successful requests, such a handler will not be passed the
278`X-Ash-File` header.
279
280The built-in `.notfound` handler can also be used in *match* or
281*capture* stanzas.
e7e3e593
FT
282
283EXAMPLES
284--------
285
286The *sendfile*(1) program can be used to serve HTML files as follows.
287
288--------
289match
290 filename *.html
291 fork sendfile -c text/html
292--------
293
294Assuming the PHP CGI interpreter is installed on the system, PHP
295scripts can be used with the following configuration, using the
296*callcgi*(1) program.
297
298--------
299fchild php
300 exec callcgi -p php-cgi
301match
302 filename *.php
303 handler php
304--------
305
306If there is a directory without an index file, a file listing can be
307automatically generated by the *htls*(1) program as follows.
308
309--------
310match directory
311 default
312 fork htls
313--------
314
315If you want an entire directory to be dedicated to some external SCGI
316script engine, you can use the *callscgi*(1) program to serve it as
317follows. Note that *callscgi*, and therefore the script engine itself,
318is started in the directory itself, so that arbitrary code modules or
319data files can be put directly in that directory and easily found.
320
321--------
322child foo
323 exec callscgi scgi-wsgi -p . foo
324
325capture foo
326--------
327
328AUTHOR
329------
330Fredrik Tolf <fredrik@dolda2000.com>
331
332SEE ALSO
333--------
334*ashd*(7)