X-Git-Url: http://www.dolda2000.com/gitweb/?p=ashd.git;a=blobdiff_plain;f=doc%2Fpatplex.doc;h=a9ebe69dd4c949584c715640ba4c19740925803a;hp=657bd45c9af9e2c57d7bf13cba87e13004a3f6e3;hb=597edd91dd69eece8ef716e8113d3e2cc4d03d37;hpb=1406acb56481b06889f6a1aa1d331f48e7150059 diff --git a/doc/patplex.doc b/doc/patplex.doc index 657bd45..a9ebe69 100644 --- a/doc/patplex.doc +++ b/doc/patplex.doc @@ -35,20 +35,24 @@ 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. +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* and -*fchild* stanzas are also shared with *dirplex*(1), so see its manpage -for a description thereof. +*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 @@ -63,14 +67,15 @@ rules are recognized: 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'. + 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. + matched case-independently. See also URL UNQUOTING, below. *method* 'REGEX' 'FLAGS':: @@ -87,28 +92,70 @@ rules are recognized: 'HEADER', the rule never matches. If 'FLAGS' contain the character `i`, 'REGEX' is matched case-independently. +*all*:: + + The rule always matches. + *default*:: - Matches if and only if no *match* stanza without a *default* - rule has matched. + 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 mathces. Currently, -only the *handler* action is recognized: +follow-up line specifying the action to take if it matches. The +following actions are supported: *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 a *restpat* line: +*reparse*:: + + Apply any side-effects as required by the match stanza (such + as rest-string or header modifications), and then retry the + matching of the request. During the rematching, the stanza + containing the *reparse* action will be disabled. Multiple + *reparse* stanzas may be used recursively. + +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. + the following parameters are recognized and expanded. At most + one *restpat* line may be given per *match* stanza. *$0* ... *$9*:: @@ -135,6 +182,31 @@ Additionally, a *match* stanza may contain a *restpat* line: 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 -------- @@ -145,7 +217,7 @@ them. -------- child root - exec sudo -u www-data dirplex /srv/www/htdocs + exec sudo -u www-data dirplex /srv/www child userdir exec userplex -g users match @@ -173,7 +245,7 @@ match # Use the last level of the domain name to enter a subdirectory. match header host ^([^.]*)\\.multi\\.org$ is - restpat $1$_ + restpat $1/$_ handler site-multi --------