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,
28 following the procedure described below under SIGNALS.
33 'PORTSPEC' is given in the form
34 'HANDLER'[*:*'PAR'[*=*'VAL'][(*,*'PAR'[*=*'VAL'])...]]. The
35 'PAR'='VAL' pairs are used for specifying key-value arguments to the
36 'HANDLER'. An example of a valid 'PORTSPEC' is `plain:port=8080`.
38 Currently, the available 'HANDLERs' are *plain* and *ssl*, for
39 handling plain TCP connections and SSL/TLS-protected connections,
40 respectively. For details regarding the arguments that each handler
41 accepts, simply run *htparser* with 'HANDLER'*:help*. For example, the
42 command "`htparser ssl:help`" will display help for the *ssl* handler
43 to standard output and then exit.
45 The port specifications must be followed by the `--` argument to
46 distinguish them from the root handler specification.
53 Print a brief usage message on standard output and exit.
57 Log messages to *syslog*(3) instead of standard error. Also
58 sets the ASHD_USESYSLOG environment variable in the root
59 handler process, which indicates to the standard ashd programs
64 Daemonize after all specified ports have been successfully
65 bound and the root handler has been started.
69 Change UID to 'USER' once all specified ports have been
70 successfully bound and the root handler has been
71 started. 'USER' must be specified symbolically (i.e. not as a
76 Change root directory to 'ROOT' once all specified ports have
77 been successfully bound and the root handler has been started.
81 After having daemonized, write the PID of the new process to
84 If the *-u*, *-r* or *-p* option is presented with an empty argument,
85 it will be treated as if the option had not been given.
92 Upon first reception, `htparser` closes all listening ports
93 and the socket to the root handler, but continues to serve all
94 currently ongoing requests until none remain, not keeping the
95 connections open for keep-alive. Upon second reception,
96 `htparser` shuts down completely.
101 If the *-p* option is used to create a PID file, `htparser` will
102 follow a simple protocol to allow state monitoring for clean shutdown
103 purposes. When `htparser` is signalled to terminate, as described
104 under SIGNALS, then it appends a single newline at the end of the PID
105 file. Once all outstanding connections have been terminated, then
106 `htparser` will truncate the PID file to zero size just prior to
107 exiting. Thus, init scripts or other state-monitoring tools can know
108 that `htparser` is serving remaining connections as long as the PID
109 file contains two lines (the last of which is empty).
111 Further, when `htparser` starts, it does not overwrite the contents of
112 an existing PID file, but rather creates a new file, replacing the old
113 file. Thus, if a new instance of `htparser` is started while a
114 previous instance is still running (or serving remaining connections),
115 the PID file for the new instance will not be truncated when the
116 previous instance terminates.
118 The reason for the somewhat unorthodox protocol is that it works by
119 simply keeping the PID file open in the running process, allowing the
120 protocol to work without pathnames, and therefore even if `htparser`
121 is instructed to change root directory with the *-r* option.
126 `htparser plain -- dirplex /srv/www`::
128 This simple invocation will listen for HTTP requests on port
129 80 and use *dirplex*(1) to serve files from the /srv/www
132 `htparser plain:port=8080 -- dirplex /srv/www`::
134 The same as the previous example, but uses port 8080 instead,
135 so that it can be started without root privileges.
137 `htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`::
139 The same as above, but will listen on port 443 for SSL
140 connections as well. The file `/etc/ssl/private/web.pem` needs
141 to contain both the server certificate and its private key.
143 `htparser plain -- sudo -u www-user dirplex /srv/www`::
145 The same as above, but uses *sudo*(8) to ensure that *dirplex*
146 runs as a non-privileged user.
148 `htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`::
150 Will listen to port 80 for plain HTTP requests and use the
151 *patplex*(1) program to serve requests based on patterns
152 specified in the `/etc/ashd/rootpat` file. *htparser* will
153 daemonize, change user-ID to `nobody` and change its root
154 directory to `/var/empty` once *patplex* has been
155 started. Note that *patplex* still runs as root in the normal
156 file system, so that it can start other handler programs as
159 `htparser -f plain -- errlogger -n ashd dirplex /srv/www`::
161 The same as the first example, but will daemonize and use the
162 *errlogger*(1) program to ensure that any errors or other
163 messages written by any handler program to its stderr are
164 recorded in the *syslog*(3).
169 *htparser* strips away all headers from incoming requests that begin
170 with the `X-Ash-` prefix, and adds the following headers to requests:
174 The IP address that the client connected from. May be an IPv6
179 The client-side port number of the TCP connection.
181 *X-Ash-Server-Address*::
183 The IP address of the server where the connection was
184 accepted. May be an IPv6 address.
186 *X-Ash-Server-Port*::
188 The server-side port number of the TCP connection.
192 Either *http* or *https*, depending on whether the request was
193 received by the *plain* or the *ssl* handler.
197 Fredrik Tolf <fredrik@dolda2000.com>