Commit | Line | Data |
---|---|---|
573c55e5 FT |
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. | |
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 | ||
739f4959 FT |
80 | X-ASH HEADERS |
81 | ------------- | |
82 | ||
83 | *htparser* strips away all headers from incoming requests that begin | |
84 | with the `X-Ash-` prefix, and adds the following headers to requests: | |
85 | ||
86 | *X-Ash-Address*:: | |
87 | ||
88 | The IP address that the client connected from. May be an IPv6 | |
89 | address. | |
90 | ||
91 | *X-Ash-Port*:: | |
92 | ||
93 | The client-side port number of the TCP connection. | |
94 | ||
95 | *X-Ash-Server-Address*:: | |
96 | ||
97 | The IP address of the server where the connection was | |
98 | accepted. May be an IPv6 address. | |
99 | ||
100 | *X-Ash-Server-Port*:: | |
101 | ||
102 | The server-side port number of the TCP connection. | |
103 | ||
104 | *X-Ash-Protocol*:: | |
105 | ||
106 | Either *http* or *https*, depending on whether the request was | |
107 | received by the *plain* or the *ssl* handler. | |
108 | ||
573c55e5 FT |
109 | AUTHOR |
110 | ------ | |
111 | Fredrik Tolf <fredrik@dolda2000.com> | |
112 | ||
113 | SEE ALSO | |
114 | -------- | |
115 | *ashd*(7) |