document control connection

diff --git a/backends/innduct.c b/backends/innduct.c
index f5ab08e581d27311106a2c068c215672f6370830..2d17982fc20223b098cbb9e886924ac4f89d9f3c 100644 (file)
--- a/backends/innduct.c
+++ b/backends/innduct.c
@@ -1,7 +1,4 @@
 /*
 /*

- * todo
- *  - manpage: document control master stuff
- *

  * debugging rune:
  *  build-lfs/backends/innduct --connection-timeout=30 --no-daemon -C ../inn.conf -f `pwd`/fee sit localhost
  */
  * debugging rune:
  *  build-lfs/backends/innduct --connection-timeout=30 --no-daemon -C ../inn.conf -f `pwd`/fee sit localhost
  */


@@ -815,6 +812,8 @@ CCMD(help) {
   const ControlCommand *ccmd;
   for (ccmd=control_commands; ccmd->cmd; ccmd++)
     fprintf(cc->out, " %s\n", ccmd->cmd);
   const ControlCommand *ccmd;
   for (ccmd=control_commands; ccmd->cmd; ccmd++)
     fprintf(cc->out, " %s\n", ccmd->cmd);

+  fputs("NB: permissible arguments are not shown above."
+       "  Not all commands listed are safe.  See innduct(8).\n", cc->out);

 }
 
 CCMD(flush) {
 }
 
 CCMD(flush) {


@@ -847,11 +846,11 @@ static const ControlCommand control_commands[]= {
   { "p",             ccmd_period    },
 
 #define POKES(cmd,func)                                                        \
   { "p",             ccmd_period    },
 
 #define POKES(cmd,func)                                                        \

-  { cmd "sm",        func,           &until_flush,             1 },    \
+  { cmd "flush",     func,           &until_flush,             1 },    \

   { cmd "conn",      func,           &until_connect,           0 },    \
   { cmd "blscan",    func,           &until_backlog_nextscan,  0 },
   { cmd "conn",      func,           &until_connect,           0 },    \
   { cmd "blscan",    func,           &until_backlog_nextscan,  0 },

-POKES("prod ", ccmd_setint_period)

 POKES("next ", ccmd_setint)
 POKES("next ", ccmd_setint)

+POKES("prod ", ccmd_setint_period)

 
   { "pretend flush", ccmd_setintarg, &simulate_flush             },
   { "wedge blscan",  ccmd_setint,    &until_backlog_nextscan, -1 },
 
   { "pretend flush", ccmd_setintarg, &simulate_flush             },
   { "wedge blscan",  ccmd_setint,    &until_backlog_nextscan, -1 },

diff --git a/doc/man/innduct.8 b/doc/man/innduct.8
index 50e4a41affa18447af26b704da4165cbeafc4d2b..c6f8b701974f8bb7208a14e150d1a39059a2b3d2 100644 (file)
--- a/doc/man/innduct.8
+++ b/doc/man/innduct.8
@@ -107,17 +107,11 @@ instead of the default
 .BR inn.conf .
 .TP
 .BI \-\-ctrl-sock-dir= DIR
 .BR inn.conf .
 .TP
 .BI \-\-ctrl-sock-dir= DIR

-Bind the real control socket to a unique filename in
-.IR DIR .
-A symlink will be made pointing to the actual file used, named
-.IB feedfile _control
-in the same directory as
-.IR feedfile ,
-but since
-.IR feedfile 's
-path may be too long for an AF_UNIX socket path, innduct always
-creates the sockets in this dedicated directory which is expected to
-have a short path.  If
+Use
+.I DIR
+as the directory to contain the actual control socket.  See
+CONTROLLING INNDUCT, below.
+If

 .I DIR
 does not exist it will be created with mode 0700; if it does
 exist it must not be a symlink and must be owned by the user running
 .I DIR
 does not exist it will be created with mode 0700; if it does
 exist it must not be a symlink and must be owned by the user running


@@ -212,9 +206,9 @@ half-life of
 The default is
 .BR 100 .
 .TP
 The default is
 .BR 100 .
 .TP

-.BI \-\-reconnect-interval= PERIOD
+.BI \-\-reconnect-interval= RECONNECT-PERIOD

 Limits initiation of new connections to one each
 Limits initiation of new connections to one each

-.IR PERIOD .
+.IR RECONNECT-PERIOD .

 This applies to reconnections if the peer has been down, and also to
 ramping up the number of connections we are using after startup or in
 response to an article flood.  The default is
 This applies to reconnections if the peer has been down, and also to
 ramping up the number of connections we are using after startup or in
 response to an article flood.  The default is


@@ -236,11 +230,11 @@ we wait at least
 before offering the article again.  The default is
 .BR 50s .
 .TP
 before offering the article again.  The default is
 .BR 50s .
 .TP

-.BI \-\-backlog-rescan-interval= PERIOD
+.BI \-\-backlog-rescan-interval= BACKLOG-SCAN-PERIOD

 We scan the directory containing
 .I feedfile
 for backlog files at least every
 We scan the directory containing
 .I feedfile
 for backlog files at least every

-.IR PERIOD ,
+.IR BACKLOG-SCAN-PERIOD ,

 in case the administrator has manually dropped in a file there for
 processing.
 The default is
 in case the administrator has manually dropped in a file there for
 processing.
 The default is


@@ -293,24 +287,82 @@ The default is
 filled with random data, or one corrupt 1024-byte disk block filled
 with an inappropriate text file with a mean line length of at least
 35).
 filled with random data, or one corrupt 1024-byte disk block filled
 with an inappropriate text file with a mean line length of at least
 35).

-.SH INTERACTING WITH INNDUCT
-innduct dances a somewhat complicated dance with innd to make sure
-that everything goes smoothly and that there are no races.  (See the
-two ascii-art diagrams in innduct.c for details of the protocol.)  Do
-not mess with the feedfile and other associated files, other than as
-explained below in the section
-.BR FILES .
-.LP
+.SH CONTROLLING INNDUCT

 If you tell innd to drop the feed, innduct will (when it notices,
 which will normally be the next time it decides flushes) finish up the
 articles it has in hand now, and then exit.  It is harmless to cause
 innd to flush the feed (but innduct won't notice and flushing won't
 start a new feedfile; you have to leave that to innduct).
 .LP
 If you tell innd to drop the feed, innduct will (when it notices,
 which will normally be the next time it decides flushes) finish up the
 articles it has in hand now, and then exit.  It is harmless to cause
 innd to flush the feed (but innduct won't notice and flushing won't
 start a new feedfile; you have to leave that to innduct).
 .LP

-If you want to stop innduct you can send it SIGTERM or SIGINT, in
-which case it will report statistics so far and quickly exit.
-If innduct receives SIGKILL nothing will be broken or corrupted; you
-just won't see some of the article stats.
+If you want to stop innduct you can send it SIGTERM or SIGINT, or the
+.B stop
+control command, in which case it will report statistics so far and
+quickly exit.  If innduct receives SIGKILL nothing will be broken or
+corrupted; you just won't see some of the article stats.
+innduct listens on an AF_UNIX socket, and provides a command-line
+interface which can be used to trigger various events and for
+debugging.
+.LP
+The socket is called
+.IB feedfile _control
+and when connected reads and writes lines (with unix line endings).
+It can most easily be accessed with a program like
+.I netcat-openbsd
+(eg
+.B nc.openbsd -U
+.IR feedfile \fB_control\fR)
+or
+.IR socat .
+The CLI has as a prompt
+.IR site \fB|\fR.
+.LP
+Because there is a fairly short limit on the length of pathnames used
+for AF_UNIX sockets, innduct actually creates the socket with a unique
+name in a different dedicated subdirectory of /tmp, and makes
+.IB feedfile _control
+a symlink to the real socket.
+.LP
+The following control commands are supported:
+.TP
+.B h
+Print a list of all the commands understood.  This list includes
+undocumented commands which mess with innduct's internal state and
+should only be used by a developer in conjuction with the innduct
+source code.
+.TP
+.B flush
+Start a new feed file and trigger a flush of the feed.
+.TP
+.B stop
+Log statistics and exit.  (Same effect as SIGTERM or SIGINT.)
+.TP
+.BR "dump q" | a
+Writes information about innduct's state to a plain text file
+.IR feedfile \fB_dump\fR.
+This overwrites any previous dump.
+.B "dump q"
+is a summary including general state and a list of connections;
+.B "dump a"
+also includes information about each article innduct is dealing with.
+.TP
+.B next blscan
+Requests that innduct rescan for new backlog files at the next
+.I PERIOD
+poll.  Normally innduct assumes that any backlog files dropped in by
+the administrator are not urgent and may not get around to noticing
+them for
+.IR BACKLOG-SCAN-PERIOD .
+.TP
+.B next conn
+Resets the connection startup delay counter so that innduct may
+consider making a new connection to the peer right away, regardless
+of the setting of
+.IR RECONNECT-PERIOD .
+A connection attempt will still only be made if innduct feels that it
+needs one, and innduct may wait up to
+.I PERIOD
+before actually starting the attempt.
+.IR BACKLOG-SCAN-PERIOD .

 .SH EXIT STATUS
 .TP
 .B 0
 .SH EXIT STATUS
 .TP
 .B 0


@@ -351,6 +403,11 @@ These exit statuses are used by children forked by innduct to
 communicate to the parent.  You should not see them.  If you do, it is
 a bug.
 .SH FILES
 communicate to the parent.  You should not see them.  If you do, it is
 a bug.
 .SH FILES

+innduct dances a somewhat complicated dance with innd to make sure
+that everything goes smoothly and that there are no races.  (See the
+two ascii-art diagrams in innduct.c for details of the protocol.)  Do
+not mess with the feedfile and other associated files, other than as
+explained here:

 .IX Header "FILES"
 .IP \fIpathoutgoing\fR/\fIsite\fR
 .IX Item "default feedfile"
 .IX Header "FILES"
 .IP \fIpathoutgoing\fR/\fIsite\fR
 .IX Item "default feedfile"