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