doc: Describe htparser shutdown behavior.

[ashd.git] / doc / htparser.doc

htparser(1)
===========

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

SYNOPSIS
--------
*htparser* [*-hSf*] [*-u* 'USER'] [*-r* 'ROOT'] [*-p* 'PIDFILE'] 'PORTSPEC'... `--` 'ROOT' ['ARGS'...]

DESCRIPTION
-----------

The *htparser* program is the root HTTP server of *ashd*(7). It
listens to specified TCP ports, speaks HTTP with connecting clients,
and passes requests on to the root handler program.

When *htparser* starts, it will first begin listening to all ports
specified by 'PORTSPEC'. Once all ports have been bound successfully,
it will fork off and start the root handler specified by 'ROOT',
searching the *PATH* environment variable if necessary, and passing it
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.

PORT SPECIFICATION
------------------

'PORTSPEC' is given in the form
'HANDLER'[*:*'PAR'[*=*'VAL'][(*,*'PAR'[*=*'VAL'])...]]. The
'PAR'='VAL' pairs are used for specifying key-value arguments to the
'HANDLER'. An example of a valid 'PORTSPEC' is `plain:port=8080`.

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
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.

OPTIONS
-------

*-h*::

	Print a brief usage message on standard output and exit.

*-S*::

	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* '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* 'ROOT'::

	Change root directory to 'ROOT' once all specified ports have
	been successfully bound and the root handler has been started.

*-p* 'PIDFILE'::

	After having daemonized, write the PID of the new process to
	'PIDFILE'.

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. Upon second
	reception, `htparser` shuts down completely.

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>

SEE ALSO
--------
*ashd*(7)