htparser(1)

Table of Contents

1. NAME
2. SYNOPSIS
3. DESCRIPTION
4. PORT SPECIFICATION
5. OPTIONS
6. SIGNALS
7. PID-FILE PROTOCOL
8. EXAMPLES
9. X-ASH HEADERS
10. AUTHOR
11. SEE ALSO

1. NAME

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

2. SYNOPSIS

htparser [-hSf] [-u USER] [-r ROOT] [-p PIDFILE] PORTSPEC… -- ROOT [ARGS…]

3. 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, following the procedure described below under SIGNALS.

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

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

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.

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

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

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

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

10. AUTHOR

Fredrik Tolf <fredrik@dolda2000.com>

11. SEE ALSO

ashd(7)