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 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)