build: Assert libmagic presence.
[ashd.git] / doc / dirplex.doc
... / ...
CommitLineData
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
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
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
58Any path element that begins with a dot is considered invalid and
59results in a 404 response to the client. If the path element names a
60directory in the current directory, the procedure continues in that
61directory. If it names a file, that file is considered the result of
62the mapping (even if the rest string has not been exhausted yet).
63
64If the path element does not name anything in the directory under
65consideration, but contains no dots, then the directory is searched
66for a file whose name before the first dot matches the path
67element. If there is such a file, it is considered the result of the
68mapping.
69
70If the result of the mapping procedure is a directory, it is checked
71for the presence of a filed named by the *index-file* configuration
72directive (see CONFIGURATION below). If there is such a file, it is
73considered the final result instead of the directory itself. If the
74index file name contains no dots and there is no exact match, then,
75again, the directory is searched for a file whose name before the
76first dot matches the index file name.
77
78CONFIGURATION
79-------------
80
81Configuration in *dirplex* comes from several sources. When *dirplex*
82starts, unless the *-N* option is given, it tries to find a global
83configuration file named `dirplex.rc`. It looks in all directories
84named by the *PATH* environment variable, appended with `../etc`. For
85example, then, if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the
86directories `/usr/local/etc`, `/etc` and `/usr/etc` are searched for
87`dirplex.rc`, in that order. Only the first file found is used, should
88there exist several.
89
90If the *-c* option is given to *dirplex*, it too specifies a
91configuration file to load. If the name given contains any slashes, it
92is opened by that exact name. Otherwise, it is searched for in the
93same manner as the global configuration file.
94
95In addition, all directories traversed by *dirplex* when mapping a URL
96into a physical file may contain a file called `.htrc`, which may
97specify extra configuration options for all files in and beneath that
98directory.
99
100`.htrc` files are checked periodically and reread if changed. The
101global configuration file and any file named by the *-c* option,
102however, are never reexamined.
103
104When using the configuration files for deciding what to do with a
105found file, they are examined in order of their "distance" from that
106file. `.htrc` files found in the directory or directories containing
107the file are considered "closest" to the file under consideration,
108followed by any configuration file named by the *-c* option, followed
109by the global configuration file.
110
111Each configuration file is a sequence of configuration stanzas, each
112stanza being an unindented starting line, followed by zero or more
113indented follow-up lines adding options to the stanza. The starting
114line of a stanza is referred to as a "configuration directive"
115below. Each line is a sequence of whitespace-separated words. A word
116may contain whitespace if such whitespace is escaped, either by
117enclosing the word in double quotes, or by escaping individual
118whitespace characters with a preceding backslash. Backslash quoting
119may also be used to treat double quotes or another backslash literally
120as part of the word. Empty lines are ignored, and lines whose first
121character after leading whitespace is a hash character (`#`) are
122treated as comments and ignored.
123
124The follow configuration directives are recognized:
125
126*index-file* ['FILENAME'...]::
127
128 The given 'FILENAMEs' are used for finding index files (see
129 URL-TO-FILE MAPPING above). Specifying *index-file* overrides
130 entirely any previous specification in a more distant
131 configuration file, rather than adding to it. Zero 'FILENAMEs'
132 may be given to turn off index file searching completely. The
133 *index-file* directive accepts no follow-up lines.
134
135*child* 'NAME'::
136
137 Declares a named, persistent request handler (see *ashd*(7)
138 for a more detailed description of persistent handlers). It
139 must contain exactly one follow-up line, *exec* 'PROGRAM'
140 ['ARGS'...], specifying the program to execute and the
141 arguments to pass it. If given in a `.htrc` file, the program
142 will be started in the same directory as the `.htrc` file
143 itself. The *child* stanza itself serves as the identity of
144 the forked process -- only one child process will be forked
145 per stanza, and if that child process exits, it will be
146 restarted the next time the stanza would be used. If a `.htrc`
147 file containing *child* stanzas is reloaded, any currently
148 running children are reused for *child* stanzas in the new
149 file with matching names (even if the *exec* line has
150 changed).
151
152*fchild* 'NAME'::
153
154 Declares a named, transient request handler (see *ashd*(7) for
155 a more detailed description of persistent handlers). It must
156 contains exactly one follow-up line, *exec* 'PROGRAM'
157 ['ARGS'...], specifying the program to execute and the
158 arguments to pass it. In addition to the specified arguments,
159 the HTTP method, raw URL and the rest string will be appended
160 added as described in *ashd*(7). If given in a `.htrc` file,
161 the program will be started in the same directory as the
162 `.htrc` file itself.
163
164*match* [*directory*]::
165
166 Specifies a filename pattern-matching rule. The
167 pattern-matching procedure and the follow-up lines accepted by
168 this stanza are described below, under MATCHING.
169
170*capture* 'HANDLER'::
171
172 Only meaningful in `.htrc` files. If a *capture* directive is
173 specified, then the URL-to-file mapping procedure as described
174 above is aborted as soon as the directory containing the
175 `.htrc` file is encountered. The request is passed, with any
176 remaining rest string, to the specified 'HANDLER', which must
177 by a named request handler specified either in the same
178 `.htrc` file or elsewhere. The *capture* directive accepts no
179 follow-up lines.
180
181MATCHING
182--------
183
184When a file or directory has been found by the mapping procedure (see
185URL-TO-FILE MAPPING above), the name of the physical file is examined
186to determine a request handler to pass the request to. Note that only
187the physical file name is ever considered; any logical request
188parameters such as the request URL or the rest string are entirely
189ignored.
190
191To match a file, any *match* stanzas specified by any `.htrc` file or
192in the global configuration files are searched in order of their
193"distance" (see CONFIGURATION above) from the actual file. If it is a
194directory which is being considered, only *match* stanzas with the
195*directory* parameter are considered; otherwise, if it is a file, only
196*match* stanzas without the *directory* parameter are considered.
197
198A *match* stanza must contain at least one follow-up line specifying
199match rules. All rules must match for the stanza as a whole to match.
200The following rules are recognized:
201
202*filename* 'PATTERN'...::
203
204 Matches if the name of the file under consideration matches
205 any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
206 pattern, such as `*.php`. See *fnmatch*(3) for more
207 information.
208
209*pathname* 'PATTERN'...::
210
211 Matches if the entire path (relative as considered from the
212 root directory being served) of the file under consideration
213 matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
214 pattern, except that slashes are not matched by wildcards. See
215 *fnmatch*(3) for more information.
216
217*default*::
218
219 Matches if and only if no *match* stanza without a *default*
220 rule has matched.
221
222In addition to the rules, a *match* stanza must contain exactly one
223follow-up line specifying the action to take if it matches. The
224following actions are recognized:
225
226*handler* 'HANDLER'::
227
228 'HANDLER' must be a named handler (see CONFIGURATION
229 above). The named handler is searched for not only in the same
230 configuration file as the *match* stanza, but in all
231 configuration files that are valid for the file under
232 consideration, in order of distance. As such, a more deeply
233 nested `.htrc` file may override the specified handler without
234 having to specify any new *match* stanzas.
235
236*fork* 'PROGRAM' ['ARGS'...]::
237
238 Run a transient handler for this file, as if it were specified
239 by a *fchild* stanza. This action exists mostly for
240 convenience.
241
242If no *match* stanza matches, a 404 response is returned to the
243client.
244
245EXAMPLES
246--------
247
248The *sendfile*(1) program can be used to serve HTML files as follows.
249
250--------
251match
252 filename *.html
253 fork sendfile -c text/html
254--------
255
256Assuming the PHP CGI interpreter is installed on the system, PHP
257scripts can be used with the following configuration, using the
258*callcgi*(1) program.
259
260--------
261fchild php
262 exec callcgi -p php-cgi
263match
264 filename *.php
265 handler php
266--------
267
268If there is a directory without an index file, a file listing can be
269automatically generated by the *htls*(1) program as follows.
270
271--------
272match directory
273 default
274 fork htls
275--------
276
277If you want an entire directory to be dedicated to some external SCGI
278script engine, you can use the *callscgi*(1) program to serve it as
279follows. Note that *callscgi*, and therefore the script engine itself,
280is started in the directory itself, so that arbitrary code modules or
281data files can be put directly in that directory and easily found.
282
283--------
284child foo
285 exec callscgi scgi-wsgi -p . foo
286
287capture foo
288--------
289
290AUTHOR
291------
292Fredrik Tolf <fredrik@dolda2000.com>
293
294SEE ALSO
295--------
296*ashd*(7)