From 595adb9922885c2a05bc6917ee8f8f02f496e618 Mon Sep 17 00:00:00 2001 From: Fredrik Tolf Date: Sat, 15 May 2021 03:55:22 +0200 Subject: [PATCH] doc: Documented htpipe. --- doc/Makefile.am | 2 +- doc/htpipe.doc | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 doc/htpipe.doc diff --git a/doc/Makefile.am b/doc/Makefile.am index baf94f3..9429bfb 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,7 +1,7 @@ dist_man1_MANS = callcgi.1 dirplex.1 htparser.1 patplex.1 sendfile.1 \ userplex.1 htls.1 callscgi.1 accesslog.1 htextauth.1 \ callfcgi.1 multifscgi.1 errlogger.1 httimed.1 \ - psendfile.1 httrcall.1 + psendfile.1 httrcall.1 htpipe.1 dist_man7_MANS = ashd.7 diff --git a/doc/htpipe.doc b/doc/htpipe.doc new file mode 100644 index 0000000..f45955d --- /dev/null +++ b/doc/htpipe.doc @@ -0,0 +1,71 @@ +htpipe(1) +========== + +NAME +---- +htpipe - Ashd decoupler pipe + +SYNOPSIS +-------- +*htpipe* [*-h*] [*-CS*] 'SOCKET-PATH' ['CHILD' ['ARGS'...]] + +DESCRIPTION +----------- + +The *htpipe* handler implements piping of *ashd*(7) requests over a +named Unix socket. The main reason for doing so would be to isolate an +*ashd*(7) handler program from the effects of restarting its parent +process. In particular, it is useful for isolating the entire handler +process tree from restarting *htparser*(1), which may be done +particularly often for such reasons as certificate renewal. + +If the *-S* flag is given to start *htpipe* in server mode, *htpipe* +will start listening to a socket named by 'SOCKET-PATH', start a +handler program as specified by 'CHILD' and 'ARGS', accept connections +on said socket, and pass requests received on such connections to the +handler program. It can handle an arbitrary amount of such +connections, but it is not implemented for high performance with a +large number of connections. It is expected that the ordinary will +involve very few connections, usually only one at a time. + +If the *-C* flag is given the start *htpipe* in client mode, *htpipe* +will connect to the socket named by 'SOCKET-PATH', accept requests +from standard input, and pass such requests over said socket, +presumably to an *htpipe* instance running in server mode on the other +end. + +By default, when neither the *-S* nor the *-C* option is given, +*htpipe* will attempt to connect to the socket named by 'SOCKET-PATH' +and, if that succeeds, go on running in client mode, just as if the +*-C* option had been given. If, however, the connection fails, it will +fork a copy of itself to run in server mode, and then reconnect to the +socket presumably created by that new process. + +*htpipe* is a persistent handler, as defined in *ashd*(7), and the +specified child handler must also be a persistent handler. + +OPTIONS +------- + +*-h*:: + + Print a brief help message to standard output and exit. + +*-C*:: + + Run in dedicated client mode, as described above. In this + mode, the 'CHILD' argument does not need to be given. + +*-S*:: + + Run in dedicated server mode, as described above. In this + mode, as well as when neither the *-C* nor the *-S* option + were given, the 'CHILD' argument is mandatory. + +AUTHOR +------ +Fredrik Tolf + +SEE ALSO +-------- +*ashd*(7) -- 2.11.0