6 htparser - Root HTTP server for use with ashd(7)
10 *htparser* [*-hSf*] [*-u* 'USER'] [*-r* 'ROOT'] [*-p* 'PIDFILE'] 'PORTSPEC'... `--` 'ROOT' ['ARGS'...]
15 The *htparser* program is the root HTTP server of *ashd*(7). It
16 listens to specified TCP ports, speaks HTTP with connecting clients,
17 and passes requests on to the root handler program.
19 When *htparser* starts, it will first begin listening to all ports
20 specified by 'PORTSPEC'. Once all ports have been bound successfully,
21 it will fork off and start the root handler specified by 'ROOT',
22 searching the *PATH* environment variable if necessary, and passing it
23 all the 'ARGS' as command-line arguments. Only after that will
24 *htparser* do any daemonizing or chrooting as specified by options.
26 The root handler must be a persistent program as specified in
27 *ashd*(7). If the handler program exits, *htparser* will exit too.
32 'PORTSPEC' is given in the form
33 'HANDLER'[*:*'PAR'[*=*'VAL'][(*,*'PAR'[*=*'VAL'])...]]. The
34 'PAR'='VAL' pairs are used for specifying key-value arguments to the
35 'HANDLER'. An example of a valid 'PORTSPEC' is `plain:port=8080`.
37 Currently, the available 'HANDLERs' are *plain* and *ssl*, for
38 handling plain TCP connections and SSL/TLS-protected connections,
39 respectively. For details regarding the arguments that each handler
40 accepts, simply run *htparser* with 'HANDLER'*:help*. For example, the
41 command "`htparser ssl:help`" will display help for the *ssl* handler
42 to standard output and then exit.
44 The port specifications must be followed by the `--` argument to
45 distinguish them from the root handler specification.
52 Print a brief usage message on standard output and exit.
56 Log messages to *syslog*(3) instead of standard error. Also
57 sets the ASHD_USESYSLOG environment variable in the root
58 handler process, which indicates to the standard ashd programs
63 Daemonize after all specified ports have been successfully
64 bound and the root handler has been started.
68 Change UID to 'USER' once all specified ports have been
69 successfully bound and the root handler has been
70 started. 'USER' must be specified symbolically (i.e. not as a
75 Change root directory to 'ROOT' once all specified ports have
76 been successfully bound and the root handler has been started.
80 After having daemonized, write the PID of the new process to
88 Upon first reception, `htparser` closes all listening ports
89 and the socket to the root handler, but continues to serve all
90 currently ongoing requests until none remain. Upon second
91 reception, `htparser` shuts down completely.
96 `htparser plain -- dirplex /srv/www`::
98 This simple invocation will listen for HTTP requests on port
99 80 and use *dirplex*(1) to serve files from the /srv/www
102 `htparser plain:port=8080 -- dirplex /srv/www`::
104 The same as the previous example, but uses port 8080 instead,
105 so that it can be started without root privileges.
107 `htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`::
109 The same as above, but will listen on port 443 for SSL
110 connections as well. The file `/etc/ssl/private/web.pem` needs
111 to contain both the server certificate and its private key.
113 `htparser plain -- sudo -u www-user dirplex /srv/www`::
115 The same as above, but uses *sudo*(8) to ensure that *dirplex*
116 runs as a non-privileged user.
118 `htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`::
120 Will listen to port 80 for plain HTTP requests and use the
121 *patplex*(1) program to serve requests based on patterns
122 specified in the `/etc/ashd/rootpat` file. *htparser* will
123 daemonize, change user-ID to `nobody` and change its root
124 directory to `/var/empty` once *patplex* has been
125 started. Note that *patplex* still runs as root in the normal
126 file system, so that it can start other handler programs as
129 `htparser -f plain -- errlogger -n ashd dirplex /srv/www`::
131 The same as the first example, but will daemonize and use the
132 *errlogger*(1) program to ensure that any errors or other
133 messages written by any handler program to its stderr are
134 recorded in the *syslog*(3).
139 *htparser* strips away all headers from incoming requests that begin
140 with the `X-Ash-` prefix, and adds the following headers to requests:
144 The IP address that the client connected from. May be an IPv6
149 The client-side port number of the TCP connection.
151 *X-Ash-Server-Address*::
153 The IP address of the server where the connection was
154 accepted. May be an IPv6 address.
156 *X-Ash-Server-Port*::
158 The server-side port number of the TCP connection.
162 Either *http* or *https*, depending on whether the request was
163 received by the *plain* or the *ssl* handler.
167 Fredrik Tolf <fredrik@dolda2000.com>