patplex: Replace the `default' handling with arbitrary priorities.

[ashd.git] / doc / patplex.doc

patplex(1)
==========

NAME
----
patplex - Request pattern matcher for ashd(7)

SYNOPSIS
--------
*patplex* [*-hN*] 'CONFIGFILE'

DESCRIPTION
-----------

The *patplex* handler matches requests against the rules specified in
'CONFIGFILE', and dispatches them to the specified handlers
accordingly. See CONFIGURATION below for a description of how requests
are matched.

*patplex* is a persistent handler, as defined in *ashd*(7).

OPTIONS
-------

*-h*::

	Print a brief help message to standard output and exit.

*-N*::

	Do not read the global configuration file `patplex.rc`.

CONFIGURATION
-------------

In addition to the 'CONFIGFILE' specified on the command-line,
*patplex* also attempts to find and read a global configuration file
called `patplex.rc`, unless the *-N* option is given. It looks in
`$HOME/.ashd/etc`, and then in all directories named by the *PATH*
environment variable, appended with `../etc/ashd`. For example, then,
if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the directories
`$HOME/.ashd/etc`, `/usr/local/etc/ashd`, `/etc/ashd` and
`/usr/etc/ashd` are searched for `patplex.rc`, in that order. Only the
first file found is used, should there exist several. If the given
'CONFIGFILE' contains any slashes, it is opened by that exact
name. Otherwise, it is searched for in the same manner as the global
configuration file.

Should the global and the given configuration files conflict, the
directives from the given file take precedence.

The configuration files follow the same general format as for
*dirplex*(1), though the recognized stanzas differ. The *child*,
*fchild* and *include* stanzas are also shared with *dirplex*(1), so
see its manpage for a description thereof.

*patplex* recognizes the *match* stanza, which takes no arguments, but
must contain at least one follow-up line to specify match rules. All
rules must match for the stanza as a whole to match. The following
rules are recognized:

*point* 'REGEX' 'FLAGS'::

	'REGEX' must be an extended regular expression. The rule is
	considered to match if 'REGEX' matches the rest string of the
	request. If 'FLAGS' contain the character `i`, 'REGEX' is
	matched case-independently. If the *match* stanza as a whole
	matches and contains no *restpat* line (as described below),
	the rest string of the request is replaced by the remainder of
	the rest string after the portion that was matched by
	'REGEX'. See also URL UNQUOTING, below.

*url* 'REGEX' 'FLAGS'::

	'REGEX' must be an extended regular expression. The rule is
	considered to match if 'REGEX' matches the raw URL of the
	request. If 'FLAGS' contain the character `i`, 'REGEX' is
	matched case-independently. See also URL UNQUOTING, below.

*method* 'REGEX' 'FLAGS'::

	'REGEX' must be an extended regular expression. The rule is
	considered to match if 'REGEX' matches the HTTP method of the
	request. If 'FLAGS' contain the character `i`, 'REGEX' is
	matched case-independently.

*header* 'HEADER' 'REGEX' 'FLAGS'::

	'REGEX' must be an extended regular expression. The rule is
	considered to match if 'REGEX' matches the named 'HEADER' in
	the request. If the request does not contain the named
	'HEADER', the rule never matches. If 'FLAGS' contain the
	character `i`, 'REGEX' is matched case-independently.

*all*::

	The rule always matches.

*default*::

	Convenient shorthand for an *all* line followed by *priority
	-10* (see below).

In addition to the rules, a *match* stanza must contain exactly one
follow-up line specifying the action to take if it matches. Currently,
only the *handler* action is recognized:

*handler* 'HANDLER'::

	'HANDLER' must be a named handler as declared by a *child* or
	*fchild* stanza, to which the request is passed.

Additionally, a *match* stanza may contain any of the following,
optional lines:

*priority* 'INTEGER'::

	Specifies the priority for the match stanza. In case more than
	one stanza match a request, the one with the highest priority
	is used. In case more than one stanza with the same highest
	priority match a request, it is unspecified which will be
	used. Match stanzas without a priority specification will
	default to priority 0. Either positive or negative priorities
	may be specified.

*order* 'INTEGER'::

	A synonym for *priority*. Use whichever you like the best.

*set* 'HEADER' 'VALUE'::

	If the *match* stanza as a whole matches, the named HTTP
	'HEADER' in the request is set to 'VALUE' before passing the
	request on to the specified handler. A *match* stanza may
	contain any number of *set* lines.

*xset* 'HEADER' 'VALUE'::

	*xset* does exactly the same thing as *set*, except that
         'HEADER' is automatically prepended with the `X-Ash-`
         prefix. The intention is only to make configuration files
         look nicer in this very common case.

*restpat* 'TEMPLATE'::

	If the *match* stanza as a whole matches, 'TEMPLATE' is
	expanded and installed as the rest string of the request
	before it is passed to the specified handler. In 'TEMPLATE',
	the following parameters are recognized and expanded. At most
	one *restpat* line may be given per *match* stanza.

*$0* ... *$9*::

	Exactly one of the *point*, *url*, *method* or *header* rules
	specified in the *match* stanza must have the `s` character
	among its 'FLAGS'. *$0* is replaced by the whole text that was
	matched by the rule's 'REGEX', and any of *$1* to *$9* is
	replaced by the corresponding parenthesized subgroup of
	'REGEX'.

*$_*::

	Replaced by the entire rest string, as it was originally.

*$$*::

	Replaced by a single *$*.

*${*'HEADER'*}*::

	Replaced by the value of the named 'HEADER' in the request, or
	the empty string if the request contained no such header.

If no *match* stanza matches, a 404 response is returned to the
client.

URL UNQUOTING
-------------

If the 'FLAGS' of a *point* or *url* rule contain the character `q`,
then the rule's pattern will be matched against a copy of the input
string where URL percent-escapes have been decoded so that, for
example, the regular expression `^~` will match an input string that
begins with either `~`, `%7E` or `%7e`.

Even if such percent-escapes were decoded, however, the original
version of the string will be used for any *restpat* expansion,
regardlessly of whether the escapes were unquoted inside or outside
the matched part of the string.

SIGNALS
-------

SIGHUP::

	Reread the given configuration file (but not the global
	file). If any named handlers, as specified by *child* stanzas,
	are currently running and have stanzas with matching names in
	the new file, they are left running for those stanzas (even if
	the *exec* line has changed).

EXAMPLES
--------

The following configuration file serves files from the `/srv/www`
directory by default, and in addition recognizes standard `/~user/`
URLs as user directories and calls the *userplex*(1) program to serve
them.

--------
child root
  exec sudo -u www-data dirplex /srv/www
child userdir
  exec userplex -g users
match
  default
  handler root
match
  point ^~
  handler userdir
--------

The following rules can be used to implement virtual hosts. The actual
handlers are left out of the example. Note that the dots in the
regular expressions need to be escaped with double backslashes, since
the configuration file reader consumes one level of quoting.

--------
# Match one exact domain name only.
match
  header host ^www\\.foo\\.net$ i
  handler site-foo
# Match any sub-domain of bar.com.
match
  header host (^|\\.)bar\\.com$ i
  handler site-bar
# Use the last level of the domain name to enter a subdirectory.
match
  header host ^([^.]*)\\.multi\\.org$ is
  restpat $1/$_
  handler site-multi
--------

AUTHOR
------
Fredrik Tolf <fredrik@dolda2000.com>

SEE ALSO
--------
*dirplex*(1), *ashd*(7), *regex*(7)