python: Added more useful logging to wsgidir.

[ashd.git] / doc / htparser.doc

diff --git a/doc/htparser.doc b/doc/htparser.doc
index cc69d57..9bace5b 100644 (file)
--- a/doc/htparser.doc
+++ b/doc/htparser.doc
@@ -3,7 +3,7 @@ htparser(1)
 
 NAME
 ----
 
 NAME
 ----

-htparser - Root HTTP server for use with *ashd*(7)
+htparser - Root HTTP server for use with ashd(7)

 
 SYNOPSIS
 --------
 
 SYNOPSIS
 --------


@@ -37,9 +37,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
 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.
 
 The port specifications must be followed by the `--` argument to
 distinguish them from the root handler specification.


@@ -53,30 +53,105 @@ OPTIONS
 
 *-S*::
 
 
 *-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.
 
 
 *-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).
 
 
        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.
 
 
        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'.
 
 
        After having daemonized, write the PID of the new process to
        'PIDFILE'.
 

+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 <fredrik@dolda2000.com>
 AUTHOR
 ------
 Fredrik Tolf <fredrik@dolda2000.com>