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 *all*::
  96
  97         The rule always matches.
  98
  99 *default*::
 100
 101         Convenient shorthand for an *all* line followed by *priority
 102         -10* (see below).
 103
 104 In addition to the rules, a *match* stanza must contain exactly one
 105 follow-up line specifying the action to take if it matches. The
 106 following actions are supported:
 107
 108 *handler* 'HANDLER'::
 109
 110         'HANDLER' must be a named handler as declared by a *child* or
 111         *fchild* stanza, to which the request is passed.
 112
 113 *reparse*::
 114
 115         Apply any side-effects as required by the match stanza (such
 116         as rest-string or header modifications), and then retry the
 117         matching of the request. During the rematching, the stanza
 118         containing the *reparse* action will be disabled. Multiple
 119         *reparse* stanzas may be used recursively.
 120
 121 Additionally, a *match* stanza may contain any of the following,
 122 optional lines:
 123
 124 *priority* 'INTEGER'::
 125
 126         Specifies the priority for the match stanza. In case more than
 127         one stanza match a request, the one with the highest priority
 128         is used. In case more than one stanza with the same highest
 129         priority match a request, it is unspecified which will be
 130         used. Match stanzas without a priority specification will
 131         default to priority 0. Either positive or negative priorities
 132         may be specified.
 133
 134 *order* 'INTEGER'::
 135
 136         A synonym for *priority*. Use whichever you like the best.
 137
 138 *set* 'HEADER' 'VALUE'::
 139
 140         If the *match* stanza as a whole matches, the named HTTP
 141         'HEADER' in the request is set to 'VALUE' before passing the
 142         request on to the specified handler. A *match* stanza may
 143         contain any number of *set* lines.
 144
 145 *xset* 'HEADER' 'VALUE'::
 146
 147         *xset* does exactly the same thing as *set*, except that
 148          'HEADER' is automatically prepended with the `X-Ash-`
 149          prefix. The intention is only to make configuration files
 150          look nicer in this very common case.
 151
 152 *restpat* 'TEMPLATE'::
 153
 154         If the *match* stanza as a whole matches, 'TEMPLATE' is
 155         expanded and installed as the rest string of the request
 156         before it is passed to the specified handler. In 'TEMPLATE',
 157         the following parameters are recognized and expanded. At most
 158         one *restpat* line may be given per *match* stanza.
 159
 160 *$0* ... *$9*::
 161
 162         Exactly one of the *point*, *url*, *method* or *header* rules
 163         specified in the *match* stanza must have the `s` character
 164         among its 'FLAGS'. *$0* is replaced by the whole text that was
 165         matched by the rule's 'REGEX', and any of *$1* to *$9* is
 166         replaced by the corresponding parenthesized subgroup of
 167         'REGEX'.
 168
 169 *$_*::
 170
 171         Replaced by the entire rest string, as it was originally.
 172
 173 *$$*::
 174
 175         Replaced by a single *$*.
 176
 177 *${*'HEADER'*}*::
 178
 179         Replaced by the value of the named 'HEADER' in the request, or
 180         the empty string if the request contained no such header.
 181
 182 If no *match* stanza matches, a 404 response is returned to the
 183 client.
 184
 185 URL UNQUOTING
 186 -------------
 187
 188 If the 'FLAGS' of a *point* or *url* rule contain the character `q`,
 189 then the rule's pattern will be matched against a copy of the input
 190 string where URL percent-escapes have been decoded so that, for
 191 example, the regular expression `^~` will match an input string that
 192 begins with either `~`, `%7E` or `%7e`.
 193
 194 Even if such percent-escapes were decoded, however, the original
 195 version of the string will be used for any *restpat* expansion,
 196 regardlessly of whether the escapes were unquoted inside or outside
 197 the matched part of the string.
 198
 199 SIGNALS
 200 -------
 201
 202 SIGHUP::
 203
 204         Reread the given configuration file (but not the global
 205         file). If any named handlers, as specified by *child* stanzas,
 206         are currently running and have stanzas with matching names in
 207         the new file, they are left running for those stanzas (even if
 208         the *exec* line has changed).
 209
 210 EXAMPLES
 211 --------
 212
 213 The following configuration file serves files from the `/srv/www`
 214 directory by default, and in addition recognizes standard `/~user/`
 215 URLs as user directories and calls the *userplex*(1) program to serve
 216 them.
 217
 218 --------
 219 child root
 220   exec sudo -u www-data dirplex /srv/www
 221 child userdir
 222   exec userplex -g users
 223 match
 224   default
 225   handler root
 226 match
 227   point ^~
 228   handler userdir
 229 --------
 230
 231 The following rules can be used to implement virtual hosts. The actual
 232 handlers are left out of the example. Note that the dots in the
 233 regular expressions need to be escaped with double backslashes, since
 234 the configuration file reader consumes one level of quoting.
 235
 236 --------
 237 # Match one exact domain name only.
 238 match
 239   header host ^www\\.foo\\.net$ i
 240   handler site-foo
 241 # Match any sub-domain of bar.com.
 242 match
 243   header host (^|\\.)bar\\.com$ i
 244   handler site-bar
 245 # Use the last level of the domain name to enter a subdirectory.
 246 match
 247   header host ^([^.]*)\\.multi\\.org$ is
 248   restpat $1/$_
 249   handler site-multi
 250 --------
 251
 252 AUTHOR
 253 ------
 254 Fredrik Tolf <fredrik@dolda2000.com>
 255
 256 SEE ALSO
 257 --------
 258 *dirplex*(1), *ashd*(7), *regex*(7)