Commit | Line | Data |
---|---|---|
1406acb5 FT |
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 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. | |
44 | ||
45 | Should the global and the given configuration files conflict, the | |
46 | directives from the given file take precedence. | |
47 | ||
48 | The configuration files follow the same general format as for | |
aa7e4406 FT |
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. | |
1406acb5 FT |
52 | |
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 | |
56 | rules are recognized: | |
57 | ||
58 | *point* 'REGEX' 'FLAGS':: | |
59 | ||
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'. | |
67 | ||
68 | *url* 'REGEX' 'FLAGS':: | |
69 | ||
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. | |
74 | ||
75 | *method* 'REGEX' 'FLAGS':: | |
76 | ||
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. | |
81 | ||
82 | *header* 'HEADER' 'REGEX' 'FLAGS':: | |
83 | ||
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. | |
89 | ||
90 | *default*:: | |
91 | ||
92 | Matches if and only if no *match* stanza without a *default* | |
93 | rule has matched. | |
94 | ||
95 | In addition to the rules, a *match* stanza must contain exactly one | |
fda48525 | 96 | follow-up line specifying the action to take if it matches. Currently, |
1406acb5 FT |
97 | only the *handler* action is recognized: |
98 | ||
99 | *handler* 'HANDLER':: | |
100 | ||
101 | 'HANDLER' must be a named handler as declared by a *child* or | |
102 | *fchild* stanza, to which the request is passed. | |
103 | ||
77a840e5 FT |
104 | Additionally, a *match* stanza may contain any of the following, |
105 | optional lines: | |
106 | ||
107 | *set* 'HEADER' 'VALUE':: | |
108 | ||
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. | |
1406acb5 | 113 | |
8cc893f5 FT |
114 | *xset* 'HEADER' 'VALUE':: |
115 | ||
5f746eb5 | 116 | *xset* does exactly the same thing as *set*, except that |
8cc893f5 FT |
117 | 'HEADER' is automatically prepended with the `X-Ash-` |
118 | prefix. The intention is only to make configuration files | |
119 | look nicer in this very common case. | |
120 | ||
1406acb5 FT |
121 | *restpat* 'TEMPLATE':: |
122 | ||
123 | If the *match* stanza as a whole matches, 'TEMPLATE' is | |
124 | expanded and installed as the rest string of the request | |
125 | before it is passed to the specified handler. In 'TEMPLATE', | |
77a840e5 FT |
126 | the following parameters are recognized and expanded. At most |
127 | one *restpat* line may be given per *match* stanza. | |
1406acb5 FT |
128 | |
129 | *$0* ... *$9*:: | |
130 | ||
131 | Exactly one of the *point*, *url*, *method* or *header* rules | |
132 | specified in the *match* stanza must have the `s` character | |
133 | among its 'FLAGS'. *$0* is replaced by the whole text that was | |
134 | matched by the rule's 'REGEX', and any of *$1* to *$9* is | |
135 | replaced by the corresponding parenthesized subgroup of | |
136 | 'REGEX'. | |
137 | ||
138 | *$_*:: | |
139 | ||
140 | Replaced by the entire rest string, as it was originally. | |
141 | ||
142 | *$$*:: | |
143 | ||
144 | Replaced by a single *$*. | |
145 | ||
146 | *${*'HEADER'*}*:: | |
147 | ||
148 | Replaced by the value of the named 'HEADER' in the request, or | |
149 | the empty string if the request contained no such header. | |
150 | ||
151 | If no *match* stanza matches, a 404 response is returned to the | |
152 | client. | |
153 | ||
82f45de1 FT |
154 | SIGNALS |
155 | ------- | |
156 | ||
157 | SIGHUP:: | |
158 | ||
159 | Reread the given configuration file (but not the global | |
160 | file). If any named handlers, as specified by *child* stanzas, | |
161 | are currently running and have stanzas with matching names in | |
162 | the new file, they are left running for those stanzas (even if | |
163 | the *exec* line has changed). | |
164 | ||
1406acb5 FT |
165 | EXAMPLES |
166 | -------- | |
167 | ||
168 | The following configuration file serves files from the `/srv/www` | |
169 | directory by default, and in addition recognizes standard `/~user/` | |
170 | URLs as user directories and calls the *userplex*(1) program to serve | |
171 | them. | |
172 | ||
173 | -------- | |
174 | child root | |
249cd06f | 175 | exec sudo -u www-data dirplex /srv/www |
1406acb5 FT |
176 | child userdir |
177 | exec userplex -g users | |
178 | match | |
179 | default | |
180 | handler root | |
181 | match | |
182 | point ^~ | |
183 | handler userdir | |
184 | -------- | |
185 | ||
186 | The following rules can be used to implement virtual hosts. The actual | |
187 | handlers are left out of the example. Note that the dots in the | |
188 | regular expressions need to be escaped with double backslashes, since | |
189 | the configuration file reader consumes one level of quoting. | |
190 | ||
191 | -------- | |
192 | # Match one exact domain name only. | |
193 | match | |
194 | header host ^www\\.foo\\.net$ i | |
195 | handler site-foo | |
196 | # Match any sub-domain of bar.com. | |
197 | match | |
198 | header host (^|\\.)bar\\.com$ i | |
199 | handler site-bar | |
200 | # Use the last level of the domain name to enter a subdirectory. | |
201 | match | |
202 | header host ^([^.]*)\\.multi\\.org$ is | |
249cd06f | 203 | restpat $1/$_ |
1406acb5 FT |
204 | handler site-multi |
205 | -------- | |
206 | ||
207 | AUTHOR | |
208 | ------ | |
209 | Fredrik Tolf <fredrik@dolda2000.com> | |
210 | ||
211 | SEE ALSO | |
212 | -------- | |
213 | *dirplex*(1), *ashd*(7), *regex*(7) |