dirplex: Fixed dotfile-checking typo.
[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
38called `patplex.rc`, unless the *-N* option is given. It looks in all
39directories 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
43order. Only the first file found is used, should there exist several.
44
45Should the global and the given configuration files conflict, the
46directives from the given file take precedence.
47
48The configuration files follow the same general format as for
49*dirplex*(1), though the recognized stanzas differ. The *child* and
50*fchild* stanzas are also shared with *dirplex*(1), so see its manpage
51for a description thereof.
52
53*patplex* recognizes the *match* stanza, which takes no arguments, but
54must contain at least one follow-up line to specify match rules. All
55rules must match for the stanza as a whole to match. The following
56rules 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
95In addition to the rules, a *match* stanza must contain exactly one
96follow-up line specifying the action to take if it mathces. Currently,
97only 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
104Additionally, a *match* stanza may contain a *restpat* line:
105
106*restpat* 'TEMPLATE'::
107
108 If the *match* stanza as a whole matches, 'TEMPLATE' is
109 expanded and installed as the rest string of the request
110 before it is passed to the specified handler. In 'TEMPLATE',
111 the following parameters are recognized and expanded.
112
113*$0* ... *$9*::
114
115 Exactly one of the *point*, *url*, *method* or *header* rules
116 specified in the *match* stanza must have the `s` character
117 among its 'FLAGS'. *$0* is replaced by the whole text that was
118 matched by the rule's 'REGEX', and any of *$1* to *$9* is
119 replaced by the corresponding parenthesized subgroup of
120 'REGEX'.
121
122*$_*::
123
124 Replaced by the entire rest string, as it was originally.
125
126*$$*::
127
128 Replaced by a single *$*.
129
130*${*'HEADER'*}*::
131
132 Replaced by the value of the named 'HEADER' in the request, or
133 the empty string if the request contained no such header.
134
135If no *match* stanza matches, a 404 response is returned to the
136client.
137
82f45de1
FT
138SIGNALS
139-------
140
141SIGHUP::
142
143 Reread the given configuration file (but not the global
144 file). If any named handlers, as specified by *child* stanzas,
145 are currently running and have stanzas with matching names in
146 the new file, they are left running for those stanzas (even if
147 the *exec* line has changed).
148
1406acb5
FT
149EXAMPLES
150--------
151
152The following configuration file serves files from the `/srv/www`
153directory by default, and in addition recognizes standard `/~user/`
154URLs as user directories and calls the *userplex*(1) program to serve
155them.
156
157--------
158child root
249cd06f 159 exec sudo -u www-data dirplex /srv/www
1406acb5
FT
160child userdir
161 exec userplex -g users
162match
163 default
164 handler root
165match
166 point ^~
167 handler userdir
168--------
169
170The following rules can be used to implement virtual hosts. The actual
171handlers are left out of the example. Note that the dots in the
172regular expressions need to be escaped with double backslashes, since
173the configuration file reader consumes one level of quoting.
174
175--------
176# Match one exact domain name only.
177match
178 header host ^www\\.foo\\.net$ i
179 handler site-foo
180# Match any sub-domain of bar.com.
181match
182 header host (^|\\.)bar\\.com$ i
183 handler site-bar
184# Use the last level of the domain name to enter a subdirectory.
185match
186 header host ^([^.]*)\\.multi\\.org$ is
249cd06f 187 restpat $1/$_
1406acb5
FT
188 handler site-multi
189--------
190
191AUTHOR
192------
193Fredrik Tolf <fredrik@dolda2000.com>
194
195SEE ALSO
196--------
197*dirplex*(1), *ashd*(7), *regex*(7)