6 dirplex - Physical directory handler for ashd(7)
10 *dirplex* [*-hN*] [*-c* 'CONFIG'] 'DIR'
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.
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.
25 *dirplex* is a persistent handler, as defined in *ashd*(7).
32 Print a brief help message to standard output and exit.
36 Do not read the global configuration file `dirplex.rc`.
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).
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
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).
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
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.
77 See also 404 RESPONSES below.
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
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
89 order. Only the first file found is used, should there exist several.
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.
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
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.
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.
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.
125 The follow configuration directives are recognized:
127 *include* ['FILENAME'...]::
129 Read 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.
137 *index-file* ['FILENAME'...]::
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.
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
165 Declares a named, transient request handler (see *ashd*(7) for
166 a more detailed description of transient handlers). It must
167 contain exactly one follow-up line, *exec* 'PROGRAM'
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
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`
175 *match* [*directory*]::
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.
181 *capture* 'HANDLER'::
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. Note that the `X-Ash-File` header is not
191 added to requests passed via *capture* directives.
196 When a file or directory has been found by the mapping procedure (see
197 URL-TO-FILE MAPPING above), the name of the physical file is examined
198 to determine a request handler to pass the request to. Note that only
199 the physical file name is ever considered; any logical request
200 parameters such as the request URL or the rest string are entirely
203 To match a file, any *match* stanzas specified by any `.htrc` file or
204 in the global configuration files are searched in order of their
205 "distance" (see CONFIGURATION above) from the actual file. If it is a
206 directory which is being considered, only *match* stanzas with the
207 *directory* parameter are considered; otherwise, if it is a file, only
208 *match* stanzas without the *directory* parameter are considered.
210 A *match* stanza must contain at least one follow-up line specifying
211 match rules. All rules must match for the stanza as a whole to match.
212 The following rules are recognized:
214 *filename* 'PATTERN'...::
216 Matches if the name of the file under consideration matches
217 any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
218 pattern, such as `*.php`. See *fnmatch*(3) for more
221 *pathname* 'PATTERN'...::
223 Matches if the entire path (relative as considered from the
224 root directory being served) of the file under consideration
225 matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
226 pattern, except that slashes are not matched by wildcards. See
227 *fnmatch*(3) for more information.
231 Matches if and only if no *match* stanza without a *default*
232 rule matches (in any configuration file).
236 Valid only in `.htrc` files, *local* matches if and only if
237 the file under consideration resides in the same directory as
238 the containing `.htrc` file.
240 In addition to the rules, a *match* stanza must contain exactly one
241 follow-up line specifying the action to take if it matches. The
242 following actions are recognized:
244 *handler* 'HANDLER'::
246 'HANDLER' must be a named handler (see CONFIGURATION
247 above). The named handler is searched for not only in the same
248 configuration file as the *match* stanza, but in all
249 configuration files that are valid for the file under
250 consideration, in order of distance. As such, a more deeply
251 nested `.htrc` file may override the specified handler without
252 having to specify any new *match* stanzas.
254 *fork* 'PROGRAM' ['ARGS'...]::
256 Run a transient handler for this file, as if it were specified
257 by a *fchild* stanza. This action exists mostly for
263 A HTTP 404 response is sent to the client if
265 * The mapping procedure fails to find a matching physical file;
266 * A path element is encountered during mapping which, after URL
267 unescaping, either begins with a dot or contains slashes;
268 * The mapping procedure finds a file which is neither a directory nor
270 * An empty, non-final path element is encountered during mapping; or
271 * The mapping procedure results in a file which is not matched by any
274 By default, *dirplex* will send a built-in 404 response, but any
275 `.htrc` file or global configuration may define a request handler
276 named `.notfound` to customize the behavior. Note that, unlike
277 successful requests, such a handler will not be passed the
280 The built-in `.notfound` handler can also be used in *match* or
281 *capture* stanzas (for example, to restrict access to certain files or
287 The *sendfile*(1) program can be used to serve HTML files as follows.
292 fork sendfile -c text/html
295 Assuming the PHP CGI interpreter is installed on the system, PHP
296 scripts can be used with the following configuration, using the
297 *callcgi*(1) program.
300 # To use plain CGI, which uses more resources per handled request,
301 # but less static resources:
303 exec callcgi -p php-cgi
305 # To use FastCGI, which keeps PHP running at all times, but uses less
306 # resources per handled request:
308 exec callfcgi multifscgi 5 php-cgi
315 If there is a directory without an index file, a file listing can be
316 automatically generated by the *htls*(1) program as follows.
324 The following configuration can be placed in a `.htrc` file in order
325 to dedicate the directory containing that file to some external SCGI
326 script engine. Note that *callscgi*, and therefore the script engine
327 itself, is started in the directory itself, so that arbitrary code
328 modules or data files can be put directly in that directory and easily
333 exec callscgi scgi-wsgi -p . foo
340 Fredrik Tolf <fredrik@dolda2000.com>