htparser: Add a `Server' header if none previously present.
[ashd.git] / doc / htparser.doc
... / ...
CommitLineData
1htparser(1)
2===========
3
4NAME
5----
6htparser - Root HTTP server for use with ashd(7)
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
27*ashd*(7). If the handler program exits, *htparser* will exit too.
28
29PORT 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
37Currently, the available 'HANDLERs' are *plain* and *ssl*, for
38handling plain TCP connections and SSL/TLS-protected connections,
39respectively. For details regarding the arguments that each handler
40accept, simply run *htparser* with 'HANDLER':*help*. For example, the
41command "`htparser ssl:help`" will display help for the *ssl* handler to
42standard output and then exit.
43
44The port specifications must be followed by the `--` argument to
45distinguish them from the root handler specification.
46
47OPTIONS
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.
57
58*-f*::
59
60 Daemonize after all specified ports have been successfully
61 bound and the root handler has been started.
62
63*-u*::
64
65 Change UID to 'USER' once all specified ports have been
66 successfully bound and the root handler has been
67 started. 'USER' must be specified symbolically (i.e. not as a
68 numeric UID).
69
70*-r*::
71
72 Change root directory to 'ROOT' once all specified ports have
73 been successfully bound and the root handler has been started.
74
75*-p*::
76
77 After having daemonized, write the PID of the new process to
78 'PIDFILE'.
79
80EXAMPLES
81--------
82
83`htparser plain -- dirplex /srv/www`::
84
85 This simple invocation will simply listen for HTTP requests on
86 port 80 and use *dirplex*(1) to serve files from the /srv/www
87 directory.
88
89`htparser plain:port=8080 -- dirplex /srv/www`::
90
91 The same as the previous example, but uses port 8080 instead,
92 so that it can be started without root privileges.]
93
94`htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`::
95
96 The same as above, but will listen on port 443 for SSL
97 connections as well. The file `/etc/ssl/privte/web.pem` needs
98 to contain both the server certificate and its private key.
99
100`htparser plain -- sudo -u www-user dirplex /srv/www`::
101
102 The same as above, but uses *sudo*(8) to ensure that *dirplex*
103 runs as a non-privileged user.
104
105`htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`::
106
107 Will listen to port 80 for plain HTTP requests and use the
108 *patplex*(1) program to serve requests based on patterns
109 specified in the `/etc/ashd/rootpat` file. *htparser* will
110 daemonize, change user-ID to `nobody` and change its root
111 directory to `/var/empty` once *patplex* has been
112 started. Note that *patplex* still runs as root in the normal
113 file system, so that it can start other handler programs as
114 needed.
115
116X-ASH HEADERS
117-------------
118
119*htparser* strips away all headers from incoming requests that begin
120 with the `X-Ash-` prefix, and adds the following headers to requests:
121
122*X-Ash-Address*::
123
124 The IP address that the client connected from. May be an IPv6
125 address.
126
127*X-Ash-Port*::
128
129 The client-side port number of the TCP connection.
130
131*X-Ash-Server-Address*::
132
133 The IP address of the server where the connection was
134 accepted. May be an IPv6 address.
135
136*X-Ash-Server-Port*::
137
138 The server-side port number of the TCP connection.
139
140*X-Ash-Protocol*::
141
142 Either *http* or *https*, depending on whether the request was
143 received by the *plain* or the *ssl* handler.
144
145AUTHOR
146------
147Fredrik Tolf <fredrik@dolda2000.com>
148
149SEE ALSO
150--------
151*ashd*(7)