6 patplex - Request pattern matcher for ashd(7)
10 *patplex* [*-hN*] 'CONFIGFILE'
15 The *patplex* handler matches requests against the rules specified in
16 'CONFIGFILE', and dispatches them to the specified handlers
17 accordingly. See CONFIGURATION below for a description of how requests
20 *patplex* is a persistent handler, as defined in *ashd*(7).
27 Print a brief help message to standard output and exit.
31 Do not read the global configuration file `patplex.rc`.
36 In addition to the 'CONFIGFILE' specified on the command-line,
37 *patplex* also attempts to find and read a global configuration file
38 called `patplex.rc`, unless the *-N* option is given. It looks in
39 `$HOME/.ashd/etc`, and then in all directories named by the *PATH*
40 environment variable, appended with `../etc/ashd`. For example, then,
41 if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the directories
42 `$HOME/.ashd/etc`, `/usr/local/etc/ashd`, `/etc/ashd` and
43 `/usr/etc/ashd` are searched for `patplex.rc`, in that order. Only the
44 first file found is used, should there exist several. If the given
45 'CONFIGFILE' contains any slashes, it is opened by that exact
46 name. Otherwise, it is searched for in the same manner as the global
49 Should the global and the given configuration files conflict, the
50 directives from the given file take precedence.
52 The configuration files follow the same general format as for
53 *dirplex*(1), though the recognized stanzas differ. The *child*,
54 *fchild* and *include* stanzas are also shared with *dirplex*(1), so
55 see its manpage for a description thereof.
57 *patplex* recognizes the *match* stanza, which takes no arguments, but
58 must contain at least one follow-up line to specify match rules. All
59 rules must match for the stanza as a whole to match. The following
62 *point* 'REGEX' 'FLAGS'::
64 'REGEX' must be an extended regular expression. The rule is
65 considered to match if 'REGEX' matches the rest string of the
66 request. If 'FLAGS' contain the character `i`, 'REGEX' is
67 matched case-independently. If the *match* stanza as a whole
68 matches and contains no *restpat* line (as described below),
69 the rest string of the request is replaced by the remainder of
70 the rest string after the portion that was matched by
71 'REGEX'. See also URL UNQUOTING, below.
73 *url* 'REGEX' 'FLAGS'::
75 'REGEX' must be an extended regular expression. The rule is
76 considered to match if 'REGEX' matches the raw URL of the
77 request. If 'FLAGS' contain the character `i`, 'REGEX' is
78 matched case-independently. See also URL UNQUOTING, below.
80 *method* 'REGEX' 'FLAGS'::
82 'REGEX' must be an extended regular expression. The rule is
83 considered to match if 'REGEX' matches the HTTP method of the
84 request. If 'FLAGS' contain the character `i`, 'REGEX' is
85 matched case-independently.
87 *header* 'HEADER' 'REGEX' 'FLAGS'::
89 'REGEX' must be an extended regular expression. The rule is
90 considered to match if 'REGEX' matches the named 'HEADER' in
91 the request. If the request does not contain the named
92 'HEADER', the rule never matches. If 'FLAGS' contain the
93 character `i`, 'REGEX' is matched case-independently.
97 Matches if and only if no *match* stanza without a *default*
100 In addition to the rules, a *match* stanza must contain exactly one
101 follow-up line specifying the action to take if it matches. Currently,
102 only the *handler* action is recognized:
104 *handler* 'HANDLER'::
106 'HANDLER' must be a named handler as declared by a *child* or
107 *fchild* stanza, to which the request is passed.
109 Additionally, a *match* stanza may contain any of the following,
112 *set* 'HEADER' 'VALUE'::
114 If the *match* stanza as a whole matches, the named HTTP
115 'HEADER' in the request is set to 'VALUE' before passing the
116 request on to the specified handler. A *match* stanza may
117 contain any number of *set* lines.
119 *xset* 'HEADER' 'VALUE'::
121 *xset* does exactly the same thing as *set*, except that
122 'HEADER' is automatically prepended with the `X-Ash-`
123 prefix. The intention is only to make configuration files
124 look nicer in this very common case.
126 *restpat* 'TEMPLATE'::
128 If the *match* stanza as a whole matches, 'TEMPLATE' is
129 expanded and installed as the rest string of the request
130 before it is passed to the specified handler. In 'TEMPLATE',
131 the following parameters are recognized and expanded. At most
132 one *restpat* line may be given per *match* stanza.
136 Exactly one of the *point*, *url*, *method* or *header* rules
137 specified in the *match* stanza must have the `s` character
138 among its 'FLAGS'. *$0* is replaced by the whole text that was
139 matched by the rule's 'REGEX', and any of *$1* to *$9* is
140 replaced by the corresponding parenthesized subgroup of
145 Replaced by the entire rest string, as it was originally.
149 Replaced by a single *$*.
153 Replaced by the value of the named 'HEADER' in the request, or
154 the empty string if the request contained no such header.
156 If no *match* stanza matches, a 404 response is returned to the
162 If the 'FLAGS' of a *point* or *url* rule contain the character `q`,
163 then the rule's pattern will be matched against a copy of the input
164 string where URL percent-escapes have been decoded so that, for
165 example, the regular expression `^~` will match an input string that
166 begins with either `~`, `%7E` or `%7e`.
168 Even if such percent-escapes were decoded, however, the original
169 version of the string will be used for any *restpat* expansion,
170 regardlessly of whether the escapes were unquoted inside or outside
171 the matched part of the string.
178 Reread the given configuration file (but not the global
179 file). If any named handlers, as specified by *child* stanzas,
180 are currently running and have stanzas with matching names in
181 the new file, they are left running for those stanzas (even if
182 the *exec* line has changed).
187 The following configuration file serves files from the `/srv/www`
188 directory by default, and in addition recognizes standard `/~user/`
189 URLs as user directories and calls the *userplex*(1) program to serve
194 exec sudo -u www-data dirplex /srv/www
196 exec userplex -g users
205 The following rules can be used to implement virtual hosts. The actual
206 handlers are left out of the example. Note that the dots in the
207 regular expressions need to be escaped with double backslashes, since
208 the configuration file reader consumes one level of quoting.
211 # Match one exact domain name only.
213 header host ^www\\.foo\\.net$ i
215 # Match any sub-domain of bar.com.
217 header host (^|\\.)bar\\.com$ i
219 # Use the last level of the domain name to enter a subdirectory.
221 header host ^([^.]*)\\.multi\\.org$ is
228 Fredrik Tolf <fredrik@dolda2000.com>
232 *dirplex*(1), *ashd*(7), *regex*(7)