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