doc/htpipe.doc

   1 htpipe(1)
   2 ==========
   3
   4 NAME
   5 ----
   6 htpipe - Ashd decoupler pipe
   7
   8 SYNOPSIS
   9 --------
  10 *htpipe* [*-h*] [*-CS*] 'SOCKET-PATH' ['CHILD' ['ARGS'...]]
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The *htpipe* handler implements piping of *ashd*(7) requests over a
  16 named Unix socket. The main reason for doing so would be to isolate an
  17 *ashd*(7) handler program from the effects of restarting its parent
  18 process. In particular, it is useful for isolating the entire handler
  19 process tree from restarting *htparser*(1), which may be done
  20 particularly often for such reasons as certificate renewal.
  21
  22 If the *-S* flag is given to start *htpipe* in server mode, *htpipe*
  23 will start listening to a socket named by 'SOCKET-PATH', start a
  24 handler program as specified by 'CHILD' and 'ARGS', accept connections
  25 on said socket, and pass requests received on such connections to the
  26 handler program. It can handle an arbitrary amount of such
  27 connections, but it is not implemented for high performance with a
  28 large number of connections. It is expected that the ordinary case
  29 will involve very few connections, usually only one at a time.
  30
  31 If the *-C* flag is given to start *htpipe* in client mode, *htpipe*
  32 will connect to the socket named by 'SOCKET-PATH', accept requests
  33 from standard input, and pass such requests over said socket,
  34 presumably to an *htpipe* instance running in server mode on the other
  35 end.
  36
  37 By default, when neither the *-S* nor the *-C* option is given,
  38 *htpipe* will attempt to connect to the socket named by 'SOCKET-PATH'
  39 and, if that succeeds, go on running in client mode, just as if the
  40 *-C* option had been given. If, however, the connection fails, it will
  41 fork a copy of itself to run in server mode, and then reconnect to the
  42 socket presumably created by that new process.
  43
  44 *htpipe* is a persistent handler, as defined in *ashd*(7), and the
  45 specified child handler must also be a persistent handler.
  46
  47 OPTIONS
  48 -------
  49
  50 *-h*::
  51
  52         Print a brief help message to standard output and exit.
  53
  54 *-C*::
  55
  56         Run in dedicated client mode, as described above. In this
  57         mode, the 'CHILD' argument does not need to be given.
  58
  59 *-S*::
  60
  61         Run in dedicated server mode, as described above. In this
  62         mode, as well as when neither the *-C* nor the *-S* option
  63         were given, the 'CHILD' argument is mandatory.
  64
  65 AUTHOR
  66 ------
  67 Fredrik Tolf <fredrik@dolda2000.com>
  68
  69 SEE ALSO
  70 --------
  71 *ashd*(7)