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