[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 all
directories named by the *PATH* environment variable, appended with
`../etc`. For example, then, if *PATH* is
`/usr/local/bin:/bin:/usr/bin`, the directories `/usr/local/etc`,
`/etc` and `/usr/etc` are searched for `patplex.rc`, in that
order. Only the first file found is used, should there exist several.

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'.

*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.

*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.

*default*::

	Matches if and only if no *match* stanza without a *default*
	rule has matched.

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:

*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 the
         '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.

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