htparser(1)

Table of Contents

1. NAME
2. SYNOPSIS
3. DESCRIPTION
4. PORT SPECIFICATION
5. OPTIONS
6. EXAMPLES
7. X-ASH HEADERS
8. AUTHOR
9. 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.

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.

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

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

8. AUTHOR

Fredrik Tolf <fredrik@dolda2000.com>

9. SEE ALSO

ashd(7)