htparser: Made HTTP version recognition case-independent.
[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
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
2824afab
FT
40accepts, simply run *htparser* with 'HANDLER'*:help*. For example, the
41command "`htparser ssl:help`" will display help for the *ssl* handler
42to standard output and then exit.
573c55e5
FT
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
d341283f 56 Log messages to *syslog*(3) instead of standard error. Also
16c2bec3
FT
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.
573c55e5
FT
60
61*-f*::
62
63 Daemonize after all specified ports have been successfully
64 bound and the root handler has been started.
65
2824afab 66*-u* 'USER'::
573c55e5
FT
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
2824afab 73*-r* 'ROOT'::
573c55e5
FT
74
75 Change root directory to 'ROOT' once all specified ports have
76 been successfully bound and the root handler has been started.
77
2824afab 78*-p* 'PIDFILE'::
573c55e5
FT
79
80 After having daemonized, write the PID of the new process to
81 'PIDFILE'.
82
36ee2230
FT
83EXAMPLES
84--------
85
86`htparser plain -- dirplex /srv/www`::
87
16c2bec3
FT
88 This simple invocation will listen for HTTP requests on port
89 80 and use *dirplex*(1) to serve files from the /srv/www
36ee2230
FT
90 directory.
91
92`htparser plain:port=8080 -- dirplex /srv/www`::
93
94 The same as the previous example, but uses port 8080 instead,
082441e4 95 so that it can be started without root privileges.
36ee2230
FT
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
16c2bec3 100 connections as well. The file `/etc/ssl/private/web.pem` needs
36ee2230
FT
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
16c2bec3
FT
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
739f4959
FT
126X-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
573c55e5
FT
155AUTHOR
156------
157Fredrik Tolf <fredrik@dolda2000.com>
158
159SEE ALSO
160--------
161*ashd*(7)