lib: Added mblock support for kqueue.
[ashd.git] / doc / patplex.doc
CommitLineData
1406acb5
FT
1patplex(1)
2==========
3
4NAME
5----
6patplex - Request pattern matcher for ashd(7)
7
8SYNOPSIS
9--------
10*patplex* [*-hN*] 'CONFIGFILE'
11
12DESCRIPTION
13-----------
14
15The *patplex* handler matches requests against the rules specified in
16'CONFIGFILE', and dispatches them to the specified handlers
17accordingly. See CONFIGURATION below for a description of how requests
18are matched.
19
20*patplex* is a persistent handler, as defined in *ashd*(7).
21
22OPTIONS
23-------
24
25*-h*::
26
27 Print a brief help message to standard output and exit.
28
29*-N*::
30
31 Do not read the global configuration file `patplex.rc`.
32
33CONFIGURATION
34-------------
35
36In addition to the 'CONFIGFILE' specified on the command-line,
37*patplex* also attempts to find and read a global configuration file
f9a65eb2
FT
38called `patplex.rc`, unless the *-N* option is given. It looks in
39`$HOME/.ashd/etc`, and then in all directories named by the *PATH*
40environment variable, appended with `../etc/ashd`. For example, then,
41if *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
44first file found is used, should there exist several. If the given
45'CONFIGFILE' contains any slashes, it is opened by that exact
46name. Otherwise, it is searched for in the same manner as the global
47configuration file.
1406acb5
FT
48
49Should the global and the given configuration files conflict, the
50directives from the given file take precedence.
51
52The configuration files follow the same general format as for
aa7e4406
FT
53*dirplex*(1), though the recognized stanzas differ. The *child*,
54*fchild* and *include* stanzas are also shared with *dirplex*(1), so
55see its manpage for a description thereof.
1406acb5
FT
56
57*patplex* recognizes the *match* stanza, which takes no arguments, but
58must contain at least one follow-up line to specify match rules. All
59rules must match for the stanza as a whole to match. The following
60rules are recognized:
61
62*point* 'REGEX' 'FLAGS'::
63
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
4dc7f716
FT
70 the rest string after the portion that was matched by
71 'REGEX'. See also URL UNQUOTING, below.
1406acb5
FT
72
73*url* 'REGEX' 'FLAGS'::
74
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
4dc7f716 78 matched case-independently. See also URL UNQUOTING, below.
1406acb5
FT
79
80*method* 'REGEX' 'FLAGS'::
81
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.
86
87*header* 'HEADER' 'REGEX' 'FLAGS'::
88
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.
94
95*default*::
96
97 Matches if and only if no *match* stanza without a *default*
98 rule has matched.
99
100In addition to the rules, a *match* stanza must contain exactly one
fda48525 101follow-up line specifying the action to take if it matches. Currently,
1406acb5
FT
102only the *handler* action is recognized:
103
104*handler* 'HANDLER'::
105
106 'HANDLER' must be a named handler as declared by a *child* or
107 *fchild* stanza, to which the request is passed.
108
77a840e5
FT
109Additionally, a *match* stanza may contain any of the following,
110optional lines:
111
112*set* 'HEADER' 'VALUE'::
113
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.
1406acb5 118
8cc893f5
FT
119*xset* 'HEADER' 'VALUE'::
120
5f746eb5 121 *xset* does exactly the same thing as *set*, except that
8cc893f5
FT
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.
125
1406acb5
FT
126*restpat* 'TEMPLATE'::
127
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',
77a840e5
FT
131 the following parameters are recognized and expanded. At most
132 one *restpat* line may be given per *match* stanza.
1406acb5
FT
133
134*$0* ... *$9*::
135
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
141 'REGEX'.
142
143*$_*::
144
145 Replaced by the entire rest string, as it was originally.
146
147*$$*::
148
149 Replaced by a single *$*.
150
151*${*'HEADER'*}*::
152
153 Replaced by the value of the named 'HEADER' in the request, or
154 the empty string if the request contained no such header.
155
156If no *match* stanza matches, a 404 response is returned to the
157client.
158
4dc7f716
FT
159URL UNQUOTING
160-------------
161
162If the 'FLAGS' of a *point* or *url* rule contain the character `q`,
163then the rule's pattern will be matched against a copy of the input
164string where URL percent-escapes have been decoded so that, for
165example, the regular expression `^~` will match an input string that
166begins with either `~`, `%7E` or `%7e`.
167
168Even if such percent-escapes were decoded, however, the original
169version of the string will be used for any *restpat* expansion,
170regardlessly of whether the escapes were unquoted inside or outside
171the matched part of the string.
172
82f45de1
FT
173SIGNALS
174-------
175
176SIGHUP::
177
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).
183
1406acb5
FT
184EXAMPLES
185--------
186
187The following configuration file serves files from the `/srv/www`
188directory by default, and in addition recognizes standard `/~user/`
189URLs as user directories and calls the *userplex*(1) program to serve
190them.
191
192--------
193child root
249cd06f 194 exec sudo -u www-data dirplex /srv/www
1406acb5
FT
195child userdir
196 exec userplex -g users
197match
198 default
199 handler root
200match
201 point ^~
202 handler userdir
203--------
204
205The following rules can be used to implement virtual hosts. The actual
206handlers are left out of the example. Note that the dots in the
207regular expressions need to be escaped with double backslashes, since
208the configuration file reader consumes one level of quoting.
209
210--------
211# Match one exact domain name only.
212match
213 header host ^www\\.foo\\.net$ i
214 handler site-foo
215# Match any sub-domain of bar.com.
216match
217 header host (^|\\.)bar\\.com$ i
218 handler site-bar
219# Use the last level of the domain name to enter a subdirectory.
220match
221 header host ^([^.]*)\\.multi\\.org$ is
249cd06f 222 restpat $1/$_
1406acb5
FT
223 handler site-multi
224--------
225
226AUTHOR
227------
228Fredrik Tolf <fredrik@dolda2000.com>
229
230SEE ALSO
231--------
232*dirplex*(1), *ashd*(7), *regex*(7)