doc/htparser.doc

   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 If the *-u*, *-r* or *-p* option is presented with an empty argument,
  85 it will be treated as if the option had not been given.
  86
  87 SIGNALS
  88 -------
  89
  90 SIGTERM, SIGINT::
  91
  92         Upon first reception, `htparser` closes all listening ports
  93         and the socket to the root handler, but continues to serve all
  94         currently ongoing requests until none remain, not keeping the
  95         connections open for keep-alive. Upon second reception,
  96         `htparser` shuts down completely.
  97
  98 PID-FILE PROTOCOL
  99 -----------------
 100
 101 If the *-p* option is used to create a PID file, `htparser` will
 102 follow a simple protocol to allow state monitoring for clean shutdown
 103 purposes. When `htparser` is signalled to terminate, as described
 104 under SIGNALS, then it appends a single newline at the end of the PID
 105 file. Once all outstanding connections have been terminated, then
 106 `htparser` will truncate the PID file to zero size just prior to
 107 exiting. Thus, init scripts or other state-monitoring tools can know
 108 that `htparser` is serving remaining connections as long as the PID
 109 file contains two lines (the last of which is empty).
 110
 111 Further, when `htparser` starts, it does not overwrite the contents of
 112 an existing PID file, but rather creates a new file, replacing the old
 113 file. Thus, if a new instance of `htparser` is started while a
 114 previous instance is still running (or serving remaining connections),
 115 the PID file for the new instance will not be truncated when the
 116 previous instance terminates.
 117
 118 The reason for the somewhat unorthodox protocol is that it works by
 119 simply keeping the PID file open in the running process, allowing the
 120 protocol to work without pathnames, and therefore even if `htparser`
 121 is instructed to change root directory with the *-r* option.
 122
 123 EXAMPLES
 124 --------
 125
 126 `htparser plain -- dirplex /srv/www`::
 127
 128         This simple invocation will listen for HTTP requests on port
 129         80 and use *dirplex*(1) to serve files from the /srv/www
 130         directory.
 131
 132 `htparser plain:port=8080 -- dirplex /srv/www`::
 133
 134         The same as the previous example, but uses port 8080 instead,
 135         so that it can be started without root privileges.
 136
 137 `htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`::
 138
 139         The same as above, but will listen on port 443 for SSL
 140         connections as well. The file `/etc/ssl/private/web.pem` needs
 141         to contain both the server certificate and its private key.
 142
 143 `htparser plain -- sudo -u www-user dirplex /srv/www`::
 144
 145         The same as above, but uses *sudo*(8) to ensure that *dirplex*
 146         runs as a non-privileged user.
 147
 148 `htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`::
 149
 150         Will listen to port 80 for plain HTTP requests and use the
 151         *patplex*(1) program to serve requests based on patterns
 152         specified in the `/etc/ashd/rootpat` file. *htparser* will
 153         daemonize, change user-ID to `nobody` and change its root
 154         directory to `/var/empty` once *patplex* has been
 155         started. Note that *patplex* still runs as root in the normal
 156         file system, so that it can start other handler programs as
 157         needed.
 158
 159 `htparser -f plain -- errlogger -n ashd dirplex /srv/www`::
 160
 161         The same as the first example, but will daemonize and use the
 162         *errlogger*(1) program to ensure that any errors or other
 163         messages written by any handler program to its stderr are
 164         recorded in the *syslog*(3).
 165
 166 X-ASH HEADERS
 167 -------------
 168
 169 *htparser* strips away all headers from incoming requests that begin
 170  with the `X-Ash-` prefix, and adds the following headers to requests:
 171
 172 *X-Ash-Address*::
 173
 174         The IP address that the client connected from. May be an IPv6
 175         address.
 176
 177 *X-Ash-Port*::
 178
 179         The client-side port number of the TCP connection.
 180
 181 *X-Ash-Server-Address*::
 182
 183         The IP address of the server where the connection was
 184         accepted. May be an IPv6 address.
 185
 186 *X-Ash-Server-Port*::
 187
 188         The server-side port number of the TCP connection.
 189
 190 *X-Ash-Protocol*::
 191
 192         Either *http* or *https*, depending on whether the request was
 193         received by the *plain* or the *ssl* handler.
 194
 195 AUTHOR
 196 ------
 197 Fredrik Tolf <fredrik@dolda2000.com>
 198
 199 SEE ALSO
 200 --------
 201 *ashd*(7)