doc: Documented the new `htparser' behaviors.

[ashd.git] / doc / htparser.doc

diff --git a/doc/htparser.doc b/doc/htparser.doc
index 6e2c239..f400a62 100644 (file)
--- a/doc/htparser.doc
+++ b/doc/htparser.doc
@@ -24,7 +24,8 @@ all the 'ARGS' as command-line arguments. Only after that will
 *htparser* do any daemonizing or chrooting as specified by options.
 
 The root handler must be a persistent program as specified in
 *htparser* do any daemonizing or chrooting as specified by options.
 
 The root handler must be a persistent program as specified in

-*ashd*(7). If the handler program exits, *htparser* will exit too.
+*ashd*(7). If the handler program exits, *htparser* will exit too,
+following the procedure described below under SIGNALS.

 
 PORT SPECIFICATION
 ------------------
 
 PORT SPECIFICATION
 ------------------


@@ -37,9 +38,9 @@ PORT SPECIFICATION
 Currently, the available 'HANDLERs' are *plain* and *ssl*, for
 handling plain TCP connections and SSL/TLS-protected connections,
 respectively. For details regarding the arguments that each handler
 Currently, the available 'HANDLERs' are *plain* and *ssl*, for
 handling plain TCP connections and SSL/TLS-protected connections,
 respectively. For details regarding the arguments that each handler

-accept, simply run *htparser* with 'HANDLER'*:help*. For example, the
-command "`htparser ssl:help`" will display help for the *ssl* handler to
-standard output and then exit.
+accepts, simply run *htparser* with 'HANDLER'*:help*. For example, the
+command "`htparser ssl:help`" will display help for the *ssl* handler
+to standard output and then exit.

 
 The port specifications must be followed by the `--` argument to
 distinguish them from the root handler specification.
 
 The port specifications must be followed by the `--` argument to
 distinguish them from the root handler specification.


@@ -63,23 +64,62 @@ OPTIONS
        Daemonize after all specified ports have been successfully
        bound and the root handler has been started.
 
        Daemonize after all specified ports have been successfully
        bound and the root handler has been started.
 

-*-u*::
+*-u* 'USER'::

 
        Change UID to 'USER' once all specified ports have been
        successfully bound and the root handler has been
        started. 'USER' must be specified symbolically (i.e. not as a
        numeric UID).
 
 
        Change UID to 'USER' once all specified ports have been
        successfully bound and the root handler has been
        started. 'USER' must be specified symbolically (i.e. not as a
        numeric UID).
 

-*-r*::
+*-r* 'ROOT'::

 
        Change root directory to 'ROOT' once all specified ports have
        been successfully bound and the root handler has been started.
 
 
        Change root directory to 'ROOT' once all specified ports have
        been successfully bound and the root handler has been started.
 

-*-p*::
+*-p* 'PIDFILE'::

 
        After having daemonized, write the PID of the new process to
        'PIDFILE'.
 
 
        After having daemonized, write the PID of the new process to
        'PIDFILE'.
 

+If the *-u*, *-r* or *-p* option is presented with an empty argument,
+it will be treated as if the option had not been given.
+
+SIGNALS
+-------
+
+SIGTERM, SIGINT::
+
+       Upon first reception, `htparser` closes all listening ports
+       and the socket to the root handler, but continues to serve all
+       currently ongoing requests until none remain, not keeping the
+       connections open for keep-alive. Upon second reception,
+       `htparser` shuts down completely.
+
+PID-FILE PROTOCOL
+-----------------
+
+If the *-p* option is used to create a PID file, `htparser` will
+follow a simple protocol to allow state monitoring for clean shutdown
+purposes. When `htparser` is signalled to terminate, as described
+under SIGNALS, then it appends a single newline at the end of the PID
+file. Once all outstanding connections have been terminated, then
+`htparser` will truncate the PID file to zero size just prior to
+exiting. Thus, init scripts or other state-monitoring tools can know
+that `htparser` is serving remaining connections as long as the PID
+file contains two lines (the last of which is empty).
+
+Further, when `htparser` starts, it does not overwrite the contents of
+an existing PID file, but rather creates a new file, replacing the old
+file. Thus, if a new instance of `htparser` is started while a
+previous instance is still running (or serving remaining connections),
+the PID file for the new instance will not be truncated when the
+previous instance terminates.
+
+The reason for the somewhat unorthodox protocol is that it works by
+simply keeping the PID file open in the running process, allowing the
+protocol to work without pathnames, and therefore even if `htparser`
+is instructed to change root directory with the *-r* option.
+

 EXAMPLES
 --------
 
 EXAMPLES
 --------