lib: Commit missing bufio include.
[ashd.git] / doc / patplex.doc
1 patplex(1)
2 ==========
3
4 NAME
5 ----
6 patplex - Request pattern matcher for ashd(7)
7
8 SYNOPSIS
9 --------
10 *patplex* [*-hN*] 'CONFIGFILE'
11
12 DESCRIPTION
13 -----------
14
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
18 are matched.
19
20 *patplex* is a persistent handler, as defined in *ashd*(7).
21
22 OPTIONS
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
33 CONFIGURATION
34 -------------
35
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
47 configuration file.
48
49 Should the global and the given configuration files conflict, the
50 directives from the given file take precedence.
51
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.
56
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
60 rules 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
70         the rest string after the portion that was matched by
71         'REGEX'. See also URL UNQUOTING, below.
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
78         matched case-independently. See also URL UNQUOTING, below.
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
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:
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
109 Additionally, a *match* stanza may contain any of the following,
110 optional 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.
118
119 *xset* 'HEADER' 'VALUE'::
120
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.
125
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',
131         the following parameters are recognized and expanded. At most
132         one *restpat* line may be given per *match* stanza.
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
156 If no *match* stanza matches, a 404 response is returned to the
157 client.
158
159 URL UNQUOTING
160 -------------
161
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`.
167
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.
172
173 SIGNALS
174 -------
175
176 SIGHUP::
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
184 EXAMPLES
185 --------
186
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
190 them.
191
192 --------
193 child root
194   exec sudo -u www-data dirplex /srv/www
195 child userdir
196   exec userplex -g users
197 match
198   default
199   handler root
200 match
201   point ^~
202   handler userdir
203 --------
204
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.
209
210 --------
211 # Match one exact domain name only.
212 match
213   header host ^www\\.foo\\.net$ i
214   handler site-foo
215 # Match any sub-domain of bar.com.
216 match
217   header host (^|\\.)bar\\.com$ i
218   handler site-bar
219 # Use the last level of the domain name to enter a subdirectory.
220 match
221   header host ^([^.]*)\\.multi\\.org$ is
222   restpat $1/$_
223   handler site-multi
224 --------
225
226 AUTHOR
227 ------
228 Fredrik Tolf <fredrik@dolda2000.com>
229
230 SEE ALSO
231 --------
232 *dirplex*(1), *ashd*(7), *regex*(7)