From 16c2bec346ae486bd09d0b18ab276b4c89005cad Mon Sep 17 00:00:00 2001 From: Fredrik Tolf Date: Sun, 1 May 2011 22:04:18 +0200 Subject: [PATCH] doc: Fixed up various parts of the documentation a bit. --- doc/ashd.doc | 6 +++--- doc/callcgi.doc | 2 +- doc/dirplex.doc | 50 ++++++++++++++++++++++++++++++-------------------- doc/htparser.doc | 19 +++++++++++++------ 4 files changed, 47 insertions(+), 30 deletions(-) diff --git a/doc/ashd.doc b/doc/ashd.doc index eb081b7..f2790ba 100644 --- a/doc/ashd.doc +++ b/doc/ashd.doc @@ -15,9 +15,9 @@ technically. If you want a brief overview, please see the homepage at The basic premise of ashd is that of standard Unix philosophy; it consists of a number of different programs, each specialized to one precise task, passing HTTP requests around to each other in a manner -akin to standard Unix pipelines. This document describes the protocols -and conventions used between such programs that allows them to -interoperate. +akin to standard Unix pipelines. This document describes the set of +protocols and conventions used between such programs that allows them +to interoperate. REQUESTS -------- diff --git a/doc/callcgi.doc b/doc/callcgi.doc index 4564279..2a61e10 100644 --- a/doc/callcgi.doc +++ b/doc/callcgi.doc @@ -47,4 +47,4 @@ Fredrik Tolf SEE ALSO -------- -*dirplex*(1), *ashd*(7), RFC 3875 +*dirplex*(1), *ashd*(7), *callscgi*(1), *callfcgi*(1), RFC 3875 diff --git a/doc/dirplex.doc b/doc/dirplex.doc index 7d1e41f..362a5d7 100644 --- a/doc/dirplex.doc +++ b/doc/dirplex.doc @@ -126,7 +126,7 @@ The follow configuration directives are recognized: *include* ['FILENAME'...]:: - Read the the named files and act as if their contents stood in + Read the named files and act as if their contents stood in place of the *include* stanza. A 'FILENAME' may be a glob pattern, in which case all matching files are used, sorted by their filenames. If a 'FILENAME' is a relative path, it is @@ -163,7 +163,7 @@ The follow configuration directives are recognized: *fchild* 'NAME':: Declares a named, transient request handler (see *ashd*(7) for - a more detailed description of persistent handlers). It must + a more detailed description of transient handlers). It must contain exactly one follow-up line, *exec* 'PROGRAM' ['ARGS'...], specifying the program to execute and the arguments to pass it. In addition to the specified arguments, @@ -187,7 +187,8 @@ The follow configuration directives are recognized: remaining rest string, to the specified 'HANDLER', which must by a named request handler specified either in the same `.htrc` file or elsewhere. The *capture* directive accepts no - follow-up lines. + follow-up lines. Note that the `X-Ash-File` header is not + added to requests passed via *capture* directives. MATCHING -------- @@ -228,7 +229,7 @@ The following rules are recognized: *default*:: Matches if and only if no *match* stanza without a *default* - rule has matched. + rule matches (in any configuration file). *local*:: @@ -259,26 +260,26 @@ following actions are recognized: 404 RESPONSES ------------- -Any of the following cases will result in a 404 response being sent to -the client. +A HTTP 404 response is sent to the client if - * Failure of the mapping procedure to find a matching physical file. - * Presence of a path element during mapping that begins with a dot. - * A path element which, after URL unescaping, contains slashes. - * The mapping procedure finding a file which is neither a directory - nor a regular file. - * Presence of a non-final but empty path element during mapping. - * A physical file having been found which is not being matched by any + * The mapping procedure fails to find a matching physical file; + * A path element is encountered during mapping which, after URL + unescaping, either begins with a dot or contains slashes; + * The mapping procedure finds a file which is neither a directory nor + a regular file; + * An empty, non-final path element is encountered during mapping; or + * The mapping procedure results in a file which is not matched by any *match* stanza. -*dirplex* will send a built-in 404 response by default, but any +By default, *dirplex* will send a built-in 404 response, but any `.htrc` file or global configuration may define a request handler named `.notfound` to customize the behavior. Note that, unlike successful requests, such a handler will not be passed the `X-Ash-File` header. The built-in `.notfound` handler can also be used in *match* or -*capture* stanzas. +*capture* stanzas (for example, to restrict access to certain files or +directories). EXAMPLES -------- @@ -296,8 +297,16 @@ scripts can be used with the following configuration, using the *callcgi*(1) program. -------- +# To use plain CGI, which uses more resources per handled request, +# but less static resources: fchild php exec callcgi -p php-cgi + +# To use FastCGI, which keeps PHP running at all times, but uses less +# resources per handled request: +child php + exec callfcgi multifscgi 5 php-cgi + match filename *.php handler php @@ -312,11 +321,12 @@ match directory fork htls -------- -If you want an entire directory to be dedicated to some external SCGI -script engine, you can use the *callscgi*(1) program to serve it as -follows. Note that *callscgi*, and therefore the script engine itself, -is started in the directory itself, so that arbitrary code modules or -data files can be put directly in that directory and easily found. +The following configuration can be placed in a `.htrc` file in order +to dedicate the directory containing that file to some external SCGI +script engine. Note that *callscgi*, and therefore the script engine +itself, is started in the directory itself, so that arbitrary code +modules or data files can be put directly in that directory and easily +found. -------- child foo diff --git a/doc/htparser.doc b/doc/htparser.doc index 320e549..698e559 100644 --- a/doc/htparser.doc +++ b/doc/htparser.doc @@ -54,9 +54,9 @@ OPTIONS *-S*:: Log messages to *syslog*(3) instead of standard error. Also - sets the environment ASHD_USESYSLOG environment variable in - the root handler process, which indicates to the standard ashd - programs to do the same thing. + sets the ASHD_USESYSLOG environment variable in the root + handler process, which indicates to the standard ashd programs + to do the same thing. *-f*:: @@ -85,8 +85,8 @@ EXAMPLES `htparser plain -- dirplex /srv/www`:: - This simple invocation will simply listen for HTTP requests on - port 80 and use *dirplex*(1) to serve files from the /srv/www + This simple invocation will listen for HTTP requests on port + 80 and use *dirplex*(1) to serve files from the /srv/www directory. `htparser plain:port=8080 -- dirplex /srv/www`:: @@ -97,7 +97,7 @@ EXAMPLES `htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`:: The same as above, but will listen on port 443 for SSL - connections as well. The file `/etc/ssl/privte/web.pem` needs + connections as well. The file `/etc/ssl/private/web.pem` needs to contain both the server certificate and its private key. `htparser plain -- sudo -u www-user dirplex /srv/www`:: @@ -116,6 +116,13 @@ EXAMPLES file system, so that it can start other handler programs as needed. +`htparser -f plain -- errlogger -n ashd dirplex /srv/www`:: + + The same as the first example, but will daemonize and use the + *errlogger*(1) program to ensure that any errors or other + messages written by any handler program to its stderr are + recorded in the *syslog*(3). + X-ASH HEADERS ------------- -- 2.11.0