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