python: Somewhat integrate async watchers with wsgidir currency.
[ashd.git] / doc / htparser.doc
CommitLineData
573c55e5
FT
1htparser(1)
2===========
3
4NAME
5----
e7e3e593 6htparser - Root HTTP server for use with ashd(7)
573c55e5
FT
7
8SYNOPSIS
9--------
10*htparser* [*-hSf*] [*-u* 'USER'] [*-r* 'ROOT'] [*-p* 'PIDFILE'] 'PORTSPEC'... `--` 'ROOT' ['ARGS'...]
11
12DESCRIPTION
13-----------
14
15The *htparser* program is the root HTTP server of *ashd*(7). It
16listens to specified TCP ports, speaks HTTP with connecting clients,
17and passes requests on to the root handler program.
18
19When *htparser* starts, it will first begin listening to all ports
20specified by 'PORTSPEC'. Once all ports have been bound successfully,
21it will fork off and start the root handler specified by 'ROOT',
22searching the *PATH* environment variable if necessary, and passing it
23all the 'ARGS' as command-line arguments. Only after that will
24*htparser* do any daemonizing or chrooting as specified by options.
25
26The root handler must be a persistent program as specified in
ee4d8132
FT
27*ashd*(7). If the handler program exits, *htparser* will exit too,
28following the procedure described below under SIGNALS.
573c55e5
FT
29
30PORT SPECIFICATION
31------------------
32
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`.
37
38Currently, the available 'HANDLERs' are *plain* and *ssl*, for
39handling plain TCP connections and SSL/TLS-protected connections,
40respectively. For details regarding the arguments that each handler
2824afab
FT
41accepts, simply run *htparser* with 'HANDLER'*:help*. For example, the
42command "`htparser ssl:help`" will display help for the *ssl* handler
43to standard output and then exit.
573c55e5
FT
44
45The port specifications must be followed by the `--` argument to
46distinguish them from the root handler specification.
47
48OPTIONS
49-------
50
51*-h*::
52
53 Print a brief usage message on standard output and exit.
54
55*-S*::
56
d341283f 57 Log messages to *syslog*(3) instead of standard error. Also
16c2bec3
FT
58 sets the ASHD_USESYSLOG environment variable in the root
59 handler process, which indicates to the standard ashd programs
60 to do the same thing.
573c55e5
FT
61
62*-f*::
63
64 Daemonize after all specified ports have been successfully
65 bound and the root handler has been started.
66
2824afab 67*-u* 'USER'::
573c55e5
FT
68
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
72 numeric UID).
73
2824afab 74*-r* 'ROOT'::
573c55e5
FT
75
76 Change root directory to 'ROOT' once all specified ports have
77 been successfully bound and the root handler has been started.
78
2824afab 79*-p* 'PIDFILE'::
573c55e5
FT
80
81 After having daemonized, write the PID of the new process to
82 'PIDFILE'.
83
c32f292e
FT
84SIGNALS
85-------
86
87SIGTERM, SIGINT::
88
89 Upon first reception, `htparser` closes all listening ports
90 and the socket to the root handler, but continues to serve all
ee4d8132
FT
91 currently ongoing requests until none remain, not keeping the
92 connections open for keep-alive. Upon second reception,
93 `htparser` shuts down completely.
c32f292e 94
36ee2230
FT
95EXAMPLES
96--------
97
98`htparser plain -- dirplex /srv/www`::
99
16c2bec3
FT
100 This simple invocation will listen for HTTP requests on port
101 80 and use *dirplex*(1) to serve files from the /srv/www
36ee2230
FT
102 directory.
103
104`htparser plain:port=8080 -- dirplex /srv/www`::
105
106 The same as the previous example, but uses port 8080 instead,
082441e4 107 so that it can be started without root privileges.
36ee2230
FT
108
109`htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`::
110
111 The same as above, but will listen on port 443 for SSL
16c2bec3 112 connections as well. The file `/etc/ssl/private/web.pem` needs
36ee2230
FT
113 to contain both the server certificate and its private key.
114
115`htparser plain -- sudo -u www-user dirplex /srv/www`::
116
117 The same as above, but uses *sudo*(8) to ensure that *dirplex*
118 runs as a non-privileged user.
119
120`htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`::
121
122 Will listen to port 80 for plain HTTP requests and use the
123 *patplex*(1) program to serve requests based on patterns
124 specified in the `/etc/ashd/rootpat` file. *htparser* will
125 daemonize, change user-ID to `nobody` and change its root
126 directory to `/var/empty` once *patplex* has been
127 started. Note that *patplex* still runs as root in the normal
128 file system, so that it can start other handler programs as
129 needed.
130
16c2bec3
FT
131`htparser -f plain -- errlogger -n ashd dirplex /srv/www`::
132
133 The same as the first example, but will daemonize and use the
134 *errlogger*(1) program to ensure that any errors or other
135 messages written by any handler program to its stderr are
136 recorded in the *syslog*(3).
137
739f4959
FT
138X-ASH HEADERS
139-------------
140
141*htparser* strips away all headers from incoming requests that begin
142 with the `X-Ash-` prefix, and adds the following headers to requests:
143
144*X-Ash-Address*::
145
146 The IP address that the client connected from. May be an IPv6
147 address.
148
149*X-Ash-Port*::
150
151 The client-side port number of the TCP connection.
152
153*X-Ash-Server-Address*::
154
155 The IP address of the server where the connection was
156 accepted. May be an IPv6 address.
157
158*X-Ash-Server-Port*::
159
160 The server-side port number of the TCP connection.
161
162*X-Ash-Protocol*::
163
164 Either *http* or *https*, depending on whether the request was
165 received by the *plain* or the *ssl* handler.
166
573c55e5
FT
167AUTHOR
168------
169Fredrik Tolf <fredrik@dolda2000.com>
170
171SEE ALSO
172--------
173*ashd*(7)