Updated ChangeLog.
[ashd.git] / doc / htparser.doc
1 htparser(1)
2 ===========
3
4 NAME
5 ----
6 htparser - Root HTTP server for use with ashd(7)
7
8 SYNOPSIS
9 --------
10 *htparser* [*-hSf*] [*-u* 'USER'] [*-r* 'ROOT'] [*-p* 'PIDFILE'] 'PORTSPEC'... `--` 'ROOT' ['ARGS'...]
11
12 DESCRIPTION
13 -----------
14
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.
18
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.
25
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
29 PORT SPECIFICATION
30 ------------------
31
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`.
36
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 accept, simply run *htparser* with 'HANDLER'*:help*. For example, the
41 command "`htparser ssl:help`" will display help for the *ssl* handler to
42 standard output and then exit.
43
44 The port specifications must be followed by the `--` argument to
45 distinguish them from the root handler specification.
46
47 OPTIONS
48 -------
49
50 *-h*::
51
52         Print a brief usage message on standard output and exit.
53
54 *-S*::
55
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
59         to do the same thing.
60
61 *-f*::
62
63         Daemonize after all specified ports have been successfully
64         bound and the root handler has been started.
65
66 *-u*::
67
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
71         numeric UID).
72
73 *-r*::
74
75         Change root directory to 'ROOT' once all specified ports have
76         been successfully bound and the root handler has been started.
77
78 *-p*::
79
80         After having daemonized, write the PID of the new process to
81         'PIDFILE'.
82
83 EXAMPLES
84 --------
85
86 `htparser plain -- dirplex /srv/www`::
87
88         This simple invocation will listen for HTTP requests on port
89         80 and use *dirplex*(1) to serve files from the /srv/www
90         directory.
91
92 `htparser plain:port=8080 -- dirplex /srv/www`::
93
94         The same as the previous example, but uses port 8080 instead,
95         so that it can be started without root privileges.]
96
97 `htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`::
98
99         The same as above, but will listen on port 443 for SSL
100         connections as well. The file `/etc/ssl/private/web.pem` needs
101         to contain both the server certificate and its private key.
102
103 `htparser plain -- sudo -u www-user dirplex /srv/www`::
104
105         The same as above, but uses *sudo*(8) to ensure that *dirplex*
106         runs as a non-privileged user.
107
108 `htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`::
109
110         Will listen to port 80 for plain HTTP requests and use the
111         *patplex*(1) program to serve requests based on patterns
112         specified in the `/etc/ashd/rootpat` file. *htparser* will
113         daemonize, change user-ID to `nobody` and change its root
114         directory to `/var/empty` once *patplex* has been
115         started. Note that *patplex* still runs as root in the normal
116         file system, so that it can start other handler programs as
117         needed.
118
119 `htparser -f plain -- errlogger -n ashd dirplex /srv/www`::
120
121         The same as the first example, but will daemonize and use the
122         *errlogger*(1) program to ensure that any errors or other
123         messages written by any handler program to its stderr are
124         recorded in the *syslog*(3).
125
126 X-ASH HEADERS
127 -------------
128
129 *htparser* strips away all headers from incoming requests that begin
130  with the `X-Ash-` prefix, and adds the following headers to requests:
131
132 *X-Ash-Address*::
133
134         The IP address that the client connected from. May be an IPv6
135         address.
136
137 *X-Ash-Port*::
138
139         The client-side port number of the TCP connection.
140
141 *X-Ash-Server-Address*::
142
143         The IP address of the server where the connection was
144         accepted. May be an IPv6 address.
145
146 *X-Ash-Server-Port*::
147
148         The server-side port number of the TCP connection.
149
150 *X-Ash-Protocol*::
151
152         Either *http* or *https*, depending on whether the request was
153         received by the *plain* or the *ssl* handler.
154
155 AUTHOR
156 ------
157 Fredrik Tolf <fredrik@dolda2000.com>
158
159 SEE ALSO
160 --------
161 *ashd*(7)