X-Git-Url: http://www.dolda2000.com/gitweb/?a=blobdiff_plain;f=doc%2Fhtparser.doc;h=f400a62c038158505ee89fe62f0063a65a9ac26b;hb=7d1e14f405f389656604c68e18a381feabcd3d4a;hp=cc69d57cec99898aa00d9b7a71d8e5a624d6b2da;hpb=573c55e5907bd8398deb5336f1e06c52bbfc4a8c;p=ashd.git diff --git a/doc/htparser.doc b/doc/htparser.doc index cc69d57..f400a62 100644 --- a/doc/htparser.doc +++ b/doc/htparser.doc @@ -3,7 +3,7 @@ htparser(1) NAME ---- -htparser - Root HTTP server for use with *ashd*(7) +htparser - Root HTTP server for use with ashd(7) SYNOPSIS -------- @@ -24,7 +24,8 @@ all the 'ARGS' as command-line arguments. Only after that will *htparser* do any daemonizing or chrooting as specified by options. The root handler must be a persistent program as specified in -*ashd*(7). If the handler program exits, *htparser* will exit too. +*ashd*(7). If the handler program exits, *htparser* will exit too, +following the procedure described below under SIGNALS. PORT SPECIFICATION ------------------ @@ -37,9 +38,9 @@ PORT SPECIFICATION Currently, the available 'HANDLERs' are *plain* and *ssl*, for handling plain TCP connections and SSL/TLS-protected connections, respectively. For details regarding the arguments that each handler -accept, simply run *htparser* with 'HANDLER':*help*. For example, the -command "`htparser ssl:help`" will display help for the *ssl* handler to -standard output and then exit. +accepts, simply run *htparser* with 'HANDLER'*:help*. For example, the +command "`htparser ssl:help`" will display help for the *ssl* handler +to standard output and then exit. The port specifications must be followed by the `--` argument to distinguish them from the root handler specification. @@ -53,30 +54,144 @@ OPTIONS *-S*:: - Log messages to *syslog*(3) instead of standard error. + Log messages to *syslog*(3) instead of standard error. Also + sets the ASHD_USESYSLOG environment variable in the root + handler process, which indicates to the standard ashd programs + to do the same thing. *-f*:: Daemonize after all specified ports have been successfully bound and the root handler has been started. -*-u*:: +*-u* 'USER':: Change UID to 'USER' once all specified ports have been successfully bound and the root handler has been started. 'USER' must be specified symbolically (i.e. not as a numeric UID). -*-r*:: +*-r* 'ROOT':: Change root directory to 'ROOT' once all specified ports have been successfully bound and the root handler has been started. -*-p*:: +*-p* 'PIDFILE':: After having daemonized, write the PID of the new process to 'PIDFILE'. +If the *-u*, *-r* or *-p* option is presented with an empty argument, +it will be treated as if the option had not been given. + +SIGNALS +------- + +SIGTERM, SIGINT:: + + Upon first reception, `htparser` closes all listening ports + and the socket to the root handler, but continues to serve all + currently ongoing requests until none remain, not keeping the + connections open for keep-alive. Upon second reception, + `htparser` shuts down completely. + +PID-FILE PROTOCOL +----------------- + +If the *-p* option is used to create a PID file, `htparser` will +follow a simple protocol to allow state monitoring for clean shutdown +purposes. When `htparser` is signalled to terminate, as described +under SIGNALS, then it appends a single newline at the end of the PID +file. Once all outstanding connections have been terminated, then +`htparser` will truncate the PID file to zero size just prior to +exiting. Thus, init scripts or other state-monitoring tools can know +that `htparser` is serving remaining connections as long as the PID +file contains two lines (the last of which is empty). + +Further, when `htparser` starts, it does not overwrite the contents of +an existing PID file, but rather creates a new file, replacing the old +file. Thus, if a new instance of `htparser` is started while a +previous instance is still running (or serving remaining connections), +the PID file for the new instance will not be truncated when the +previous instance terminates. + +The reason for the somewhat unorthodox protocol is that it works by +simply keeping the PID file open in the running process, allowing the +protocol to work without pathnames, and therefore even if `htparser` +is instructed to change root directory with the *-r* option. + +EXAMPLES +-------- + +`htparser plain -- dirplex /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`:: + + The same as the previous example, but uses port 8080 instead, + so that it can be started without root privileges. + +`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/private/web.pem` needs + to contain both the server certificate and its private key. + +`htparser plain -- sudo -u www-user dirplex /srv/www`:: + + The same as above, but uses *sudo*(8) to ensure that *dirplex* + runs as a non-privileged user. + +`htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`:: + + Will listen to port 80 for plain HTTP requests and use the + *patplex*(1) program to serve requests based on patterns + specified in the `/etc/ashd/rootpat` file. *htparser* will + daemonize, change user-ID to `nobody` and change its root + directory to `/var/empty` once *patplex* has been + started. Note that *patplex* still runs as root in the normal + 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 +------------- + +*htparser* strips away all headers from incoming requests that begin + with the `X-Ash-` prefix, and adds the following headers to requests: + +*X-Ash-Address*:: + + The IP address that the client connected from. May be an IPv6 + address. + +*X-Ash-Port*:: + + The client-side port number of the TCP connection. + +*X-Ash-Server-Address*:: + + The IP address of the server where the connection was + accepted. May be an IPv6 address. + +*X-Ash-Server-Port*:: + + The server-side port number of the TCP connection. + +*X-Ash-Protocol*:: + + Either *http* or *https*, depending on whether the request was + received by the *plain* or the *ssl* handler. + AUTHOR ------ Fredrik Tolf