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 all
39 directories named by the *PATH* environment variable, appended with
40 `../etc`. For example, then, if *PATH* is
41 `/usr/local/bin:/bin:/usr/bin`, the directories `/usr/local/etc`,
42 `/etc` and `/usr/etc` are searched for `patplex.rc`, in that
43 order. Only the first file found is used, should there exist several.
45 Should the global and the given configuration files conflict, the
46 directives from the given file take precedence.
48 The configuration files follow the same general format as for
49 *dirplex*(1), though the recognized stanzas differ. The *child*,
50 *fchild* and *include* stanzas are also shared with *dirplex*(1), so
51 see its manpage for a description thereof.
53 *patplex* recognizes the *match* stanza, which takes no arguments, but
54 must contain at least one follow-up line to specify match rules. All
55 rules must match for the stanza as a whole to match. The following
58 *point* 'REGEX' 'FLAGS'::
60 'REGEX' must be an extended regular expression. The rule is
61 considered to match if 'REGEX' matches the rest string of the
62 request. If 'FLAGS' contain the character `i`, 'REGEX' is
63 matched case-independently. If the *match* stanza as a whole
64 matches and contains no *restpat* line (as described below),
65 the rest string of the request is replaced by the remainder of
66 the rest string after the portion that was matched by 'REGEX'.
68 *url* 'REGEX' 'FLAGS'::
70 'REGEX' must be an extended regular expression. The rule is
71 considered to match if 'REGEX' matches the raw URL of the
72 request. If 'FLAGS' contain the character `i`, 'REGEX' is
73 matched case-independently.
75 *method* 'REGEX' 'FLAGS'::
77 'REGEX' must be an extended regular expression. The rule is
78 considered to match if 'REGEX' matches the HTTP method of the
79 request. If 'FLAGS' contain the character `i`, 'REGEX' is
80 matched case-independently.
82 *header* 'HEADER' 'REGEX' 'FLAGS'::
84 'REGEX' must be an extended regular expression. The rule is
85 considered to match if 'REGEX' matches the named 'HEADER' in
86 the request. If the request does not contain the named
87 'HEADER', the rule never matches. If 'FLAGS' contain the
88 character `i`, 'REGEX' is matched case-independently.
92 Matches if and only if no *match* stanza without a *default*
95 In addition to the rules, a *match* stanza must contain exactly one
96 follow-up line specifying the action to take if it mathces. Currently,
97 only the *handler* action is recognized:
101 'HANDLER' must be a named handler as declared by a *child* or
102 *fchild* stanza, to which the request is passed.
104 Additionally, a *match* stanza may contain any of the following,
107 *set* 'HEADER' 'VALUE'::
109 If the *match* stanza as a whole matches, the named HTTP
110 'HEADER' in the request is set to 'VALUE' before passing the
111 request on to the specified handler. A *match* stanza may
112 contain any number of *set* lines.
114 *restpat* 'TEMPLATE'::
116 If the *match* stanza as a whole matches, 'TEMPLATE' is
117 expanded and installed as the rest string of the request
118 before it is passed to the specified handler. In 'TEMPLATE',
119 the following parameters are recognized and expanded. At most
120 one *restpat* line may be given per *match* stanza.
124 Exactly one of the *point*, *url*, *method* or *header* rules
125 specified in the *match* stanza must have the `s` character
126 among its 'FLAGS'. *$0* is replaced by the whole text that was
127 matched by the rule's 'REGEX', and any of *$1* to *$9* is
128 replaced by the corresponding parenthesized subgroup of
133 Replaced by the entire rest string, as it was originally.
137 Replaced by a single *$*.
141 Replaced by the value of the named 'HEADER' in the request, or
142 the empty string if the request contained no such header.
144 If no *match* stanza matches, a 404 response is returned to the
152 Reread the given configuration file (but not the global
153 file). If any named handlers, as specified by *child* stanzas,
154 are currently running and have stanzas with matching names in
155 the new file, they are left running for those stanzas (even if
156 the *exec* line has changed).
161 The following configuration file serves files from the `/srv/www`
162 directory by default, and in addition recognizes standard `/~user/`
163 URLs as user directories and calls the *userplex*(1) program to serve
168 exec sudo -u www-data dirplex /srv/www
170 exec userplex -g users
179 The following rules can be used to implement virtual hosts. The actual
180 handlers are left out of the example. Note that the dots in the
181 regular expressions need to be escaped with double backslashes, since
182 the configuration file reader consumes one level of quoting.
185 # Match one exact domain name only.
187 header host ^www\\.foo\\.net$ i
189 # Match any sub-domain of bar.com.
191 header host (^|\\.)bar\\.com$ i
193 # Use the last level of the domain name to enter a subdirectory.
195 header host ^([^.]*)\\.multi\\.org$ is
202 Fredrik Tolf <fredrik@dolda2000.com>
206 *dirplex*(1), *ashd*(7), *regex*(7)