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 The rule always matches.
101 Convenient shorthand for an *all* line followed by *priority
104 In addition to the rules, a *match* stanza must contain exactly one
105 follow-up line specifying the action to take if it matches. Currently,
106 only the *handler* action is recognized:
108 *handler* 'HANDLER'::
110 'HANDLER' must be a named handler as declared by a *child* or
111 *fchild* stanza, to which the request is passed.
113 Additionally, a *match* stanza may contain any of the following,
116 *priority* 'INTEGER'::
118 Specifies the priority for the match stanza. In case more than
119 one stanza match a request, the one with the highest priority
120 is used. In case more than one stanza with the same highest
121 priority match a request, it is unspecified which will be
122 used. Match stanzas without a priority specification will
123 default to priority 0. Either positive or negative priorities
128 A synonym for *priority*. Use whichever you like the best.
130 *set* 'HEADER' 'VALUE'::
132 If the *match* stanza as a whole matches, the named HTTP
133 'HEADER' in the request is set to 'VALUE' before passing the
134 request on to the specified handler. A *match* stanza may
135 contain any number of *set* lines.
137 *xset* 'HEADER' 'VALUE'::
139 *xset* does exactly the same thing as *set*, except that
140 'HEADER' is automatically prepended with the `X-Ash-`
141 prefix. The intention is only to make configuration files
142 look nicer in this very common case.
144 *restpat* 'TEMPLATE'::
146 If the *match* stanza as a whole matches, 'TEMPLATE' is
147 expanded and installed as the rest string of the request
148 before it is passed to the specified handler. In 'TEMPLATE',
149 the following parameters are recognized and expanded. At most
150 one *restpat* line may be given per *match* stanza.
154 Exactly one of the *point*, *url*, *method* or *header* rules
155 specified in the *match* stanza must have the `s` character
156 among its 'FLAGS'. *$0* is replaced by the whole text that was
157 matched by the rule's 'REGEX', and any of *$1* to *$9* is
158 replaced by the corresponding parenthesized subgroup of
163 Replaced by the entire rest string, as it was originally.
167 Replaced by a single *$*.
171 Replaced by the value of the named 'HEADER' in the request, or
172 the empty string if the request contained no such header.
174 If no *match* stanza matches, a 404 response is returned to the
180 If the 'FLAGS' of a *point* or *url* rule contain the character `q`,
181 then the rule's pattern will be matched against a copy of the input
182 string where URL percent-escapes have been decoded so that, for
183 example, the regular expression `^~` will match an input string that
184 begins with either `~`, `%7E` or `%7e`.
186 Even if such percent-escapes were decoded, however, the original
187 version of the string will be used for any *restpat* expansion,
188 regardlessly of whether the escapes were unquoted inside or outside
189 the matched part of the string.
196 Reread the given configuration file (but not the global
197 file). If any named handlers, as specified by *child* stanzas,
198 are currently running and have stanzas with matching names in
199 the new file, they are left running for those stanzas (even if
200 the *exec* line has changed).
205 The following configuration file serves files from the `/srv/www`
206 directory by default, and in addition recognizes standard `/~user/`
207 URLs as user directories and calls the *userplex*(1) program to serve
212 exec sudo -u www-data dirplex /srv/www
214 exec userplex -g users
223 The following rules can be used to implement virtual hosts. The actual
224 handlers are left out of the example. Note that the dots in the
225 regular expressions need to be escaped with double backslashes, since
226 the configuration file reader consumes one level of quoting.
229 # Match one exact domain name only.
231 header host ^www\\.foo\\.net$ i
233 # Match any sub-domain of bar.com.
235 header host (^|\\.)bar\\.com$ i
237 # Use the last level of the domain name to enter a subdirectory.
239 header host ^([^.]*)\\.multi\\.org$ is
246 Fredrik Tolf <fredrik@dolda2000.com>
250 *dirplex*(1), *ashd*(7), *regex*(7)