Commit | Line | Data |
---|---|---|
573c55e5 FT |
1 | htparser(1) |
2 | =========== | |
3 | ||
4 | NAME | |
5 | ---- | |
e7e3e593 | 6 | htparser - Root HTTP server for use with ashd(7) |
573c55e5 FT |
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 | |
ee4d8132 FT |
27 | *ashd*(7). If the handler program exits, *htparser* will exit too, |
28 | following the procedure described below under SIGNALS. | |
573c55e5 FT |
29 | |
30 | PORT 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 | ||
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 | |
2824afab FT |
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. | |
573c55e5 FT |
44 | |
45 | The port specifications must be followed by the `--` argument to | |
46 | distinguish them from the root handler specification. | |
47 | ||
48 | OPTIONS | |
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 |
84 | SIGNALS |
85 | ------- | |
86 | ||
87 | SIGTERM, 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 |
95 | EXAMPLES |
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 |
138 | X-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 |
167 | AUTHOR |
168 | ------ | |
169 | Fredrik Tolf <fredrik@dolda2000.com> | |
170 | ||
171 | SEE ALSO | |
172 | -------- | |
173 | *ashd*(7) |