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 all
  39 directories named by the *PATH* environment variable, appended with
  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
  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.
  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
  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.
  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
  99 follow-up line specifying the action to take if it matches. Currently,
 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
 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.
 116
 117 *xset* 'HEADER' 'VALUE'::
 118
 119         *xset* does exactly the same thing as *set*, except that
 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
 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',
 129         the following parameters are recognized and expanded. At most
 130         one *restpat* line may be given per *match* stanza.
 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
 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
 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
 178   exec sudo -u www-data dirplex /srv/www
 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
 206   restpat $1/$_
 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)