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
  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 accepts, simply run *htparser* with 'HANDLER'*:help*. For example, the
  41 command "`htparser ssl:help`" will display help for the *ssl* handler
  42 to 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. Also
  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.
  60
  61 *-f*::
  62
  63         Daemonize after all specified ports have been successfully
  64         bound and the root handler has been started.
  65
  66 *-u* 'USER'::
  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
  73 *-r* 'ROOT'::
  74
  75         Change root directory to 'ROOT' once all specified ports have
  76         been successfully bound and the root handler has been started.
  77
  78 *-p* 'PIDFILE'::
  79
  80         After having daemonized, write the PID of the new process to
  81         'PIDFILE'.
  82
  83 SIGNALS
  84 -------
  85
  86 SIGTERM, SIGINT::
  87
  88         Upon first reception, `htparser` closes all listening ports
  89         and the socket to the root handler, but continues to serve all
  90         currently ongoing requests until none remain. Upon second
  91         reception, `htparser` shuts down completely.
  92
  93 EXAMPLES
  94 --------
  95
  96 `htparser plain -- dirplex /srv/www`::
  97
  98         This simple invocation will listen for HTTP requests on port
  99         80 and use *dirplex*(1) to serve files from the /srv/www
 100         directory.
 101
 102 `htparser plain:port=8080 -- dirplex /srv/www`::
 103
 104         The same as the previous example, but uses port 8080 instead,
 105         so that it can be started without root privileges.
 106
 107 `htparser plain ssl:cert=/etc/ssl/private/web.pem -- dirplex /srv/www`::
 108
 109         The same as above, but will listen on port 443 for SSL
 110         connections as well. The file `/etc/ssl/private/web.pem` needs
 111         to contain both the server certificate and its private key.
 112
 113 `htparser plain -- sudo -u www-user dirplex /srv/www`::
 114
 115         The same as above, but uses *sudo*(8) to ensure that *dirplex*
 116         runs as a non-privileged user.
 117
 118 `htparser -f -u nobody -r /var/empty plain -- patplex /etc/ashd/rootpat`::
 119
 120         Will listen to port 80 for plain HTTP requests and use the
 121         *patplex*(1) program to serve requests based on patterns
 122         specified in the `/etc/ashd/rootpat` file. *htparser* will
 123         daemonize, change user-ID to `nobody` and change its root
 124         directory to `/var/empty` once *patplex* has been
 125         started. Note that *patplex* still runs as root in the normal
 126         file system, so that it can start other handler programs as
 127         needed.
 128
 129 `htparser -f plain -- errlogger -n ashd dirplex /srv/www`::
 130
 131         The same as the first example, but will daemonize and use the
 132         *errlogger*(1) program to ensure that any errors or other
 133         messages written by any handler program to its stderr are
 134         recorded in the *syslog*(3).
 135
 136 X-ASH HEADERS
 137 -------------
 138
 139 *htparser* strips away all headers from incoming requests that begin
 140  with the `X-Ash-` prefix, and adds the following headers to requests:
 141
 142 *X-Ash-Address*::
 143
 144         The IP address that the client connected from. May be an IPv6
 145         address.
 146
 147 *X-Ash-Port*::
 148
 149         The client-side port number of the TCP connection.
 150
 151 *X-Ash-Server-Address*::
 152
 153         The IP address of the server where the connection was
 154         accepted. May be an IPv6 address.
 155
 156 *X-Ash-Server-Port*::
 157
 158         The server-side port number of the TCP connection.
 159
 160 *X-Ash-Protocol*::
 161
 162         Either *http* or *https*, depending on whether the request was
 163         received by the *plain* or the *ssl* handler.
 164
 165 AUTHOR
 166 ------
 167 Fredrik Tolf <fredrik@dolda2000.com>
 168
 169 SEE ALSO
 170 --------
 171 *ashd*(7)