| 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 | following the procedure described below under SIGNALS. |
| 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 |
| 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. |
| 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 | |
| 57 | Log messages to *syslog*(3) instead of standard error. Also |
| 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. |
| 61 | |
| 62 | *-f*:: |
| 63 | |
| 64 | Daemonize after all specified ports have been successfully |
| 65 | bound and the root handler has been started. |
| 66 | |
| 67 | *-u* 'USER':: |
| 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 | |
| 74 | *-r* 'ROOT':: |
| 75 | |
| 76 | Change root directory to 'ROOT' once all specified ports have |
| 77 | been successfully bound and the root handler has been started. |
| 78 | |
| 79 | *-p* 'PIDFILE':: |
| 80 | |
| 81 | After having daemonized, write the PID of the new process to |
| 82 | 'PIDFILE'. |
| 83 | |
| 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 |
| 91 | currently ongoing requests until none remain, not keeping the |
| 92 | connections open for keep-alive. Upon second reception, |
| 93 | `htparser` shuts down completely. |
| 94 | |
| 95 | EXAMPLES |
| 96 | -------- |
| 97 | |
| 98 | `htparser plain -- dirplex /srv/www`:: |
| 99 | |
| 100 | This simple invocation will listen for HTTP requests on port |
| 101 | 80 and use *dirplex*(1) to serve files from the /srv/www |
| 102 | directory. |
| 103 | |
| 104 | `htparser plain:port=8080 -- dirplex /srv/www`:: |
| 105 | |
| 106 | The same as the previous example, but uses port 8080 instead, |
| 107 | so that it can be started without root privileges. |
| 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 |
| 112 | connections as well. The file `/etc/ssl/private/web.pem` needs |
| 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 | |
| 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 | |
| 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 | |
| 167 | AUTHOR |
| 168 | ------ |
| 169 | Fredrik Tolf <fredrik@dolda2000.com> |
| 170 | |
| 171 | SEE ALSO |
| 172 | -------- |
| 173 | *ashd*(7) |