X-Git-Url: http://www.dolda2000.com/gitweb/?p=ashd.git;a=blobdiff_plain;f=doc%2Fhtparser.doc;h=320e549885195b08be90e4380854f880ddb62e2d;hp=cc69d57cec99898aa00d9b7a71d8e5a624d6b2da;hb=01bb89b0e602cfcc259f90388eb8e06834b60c48;hpb=573c55e5907bd8398deb5336f1e06c52bbfc4a8c

diff --git a/doc/htparser.doc b/doc/htparser.doc
index cc69d57..320e549 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
 --------
@@ -37,7 +37,7 @@ 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
+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.
 
@@ -53,7 +53,10 @@ OPTIONS
 
 *-S*::
 
-	Log messages to *syslog*(3) instead of standard error.
+	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.
 
 *-f*::
 
@@ -77,6 +80,71 @@ OPTIONS
 	After having daemonized, write the PID of the new process to
 	'PIDFILE'.
 
+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
+	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/privte/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.
+
+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>