Merge branch 'master' of login.chiark.greenend.org.uk:public-git/inn-innduct

[inn-innduct.git] / doc / man / innduct.8

diff --git a/doc/man/innduct.8 b/doc/man/innduct.8
index 055d083085466bc77731e9e0a0751a0cae9a355b..f8ecbf0724faa009a4d65dfccb3965586352eea3 100644 (file)
--- a/doc/man/innduct.8
+++ b/doc/man/innduct.8
@@ -9,7 +9,13 @@ innduct \- quickly and reliably stream Usenet articles to remote site
 .SH DESCRIPTION
 .B innduct
 implements NNTP peer-to-peer news transmission including the streaming
 .SH DESCRIPTION
 .B innduct
 implements NNTP peer-to-peer news transmission including the streaming

-extensions, for sending news articles to a remote site.
+extensions, for sending news articles to a remote site.  It is
+intended as a replacement for
+.I innfeed
+or
+.IR nntpsend
+and
+.IR innxmit .

 
 You need to run one instance of innduct for each peer site.  innduct
 manages its interaction with innd, including flushing the feed as
 
 You need to run one instance of innduct for each peer site.  innduct
 manages its interaction with innd, including flushing the feed as


@@ -20,11 +26,10 @@ locking necessary to avoid multiple simutaneous invocations.
 By default, innduct reads the default feedfile corresponding to
 the site
 .I site
 By default, innduct reads the default feedfile corresponding to
 the site
 .I site

-(is
+(ie

 .IR pathoutgoing / site )
 and feeds it via NNTP, streaming if possible, to the host
 .IR fqdn .
 .IR pathoutgoing / site )
 and feeds it via NNTP, streaming if possible, to the host
 .IR fqdn .

-

 If
 .I fqdn
 is not specified, it defaults to
 If
 .I fqdn
 is not specified, it defaults to


@@ -35,10 +40,10 @@ error messages) are sent to syslog (facility
 .BR news ).
 
 The best way to run innduct is probably to periodically invoke innduct
 .BR news ).
 
 The best way to run innduct is probably to periodically invoke innduct

-for each feed (e.g. from cron), passing innduct it the
+for each feed (e.g. from cron), passing the

 .B \-q
 .B \-q

-option to arrange that it silently exits if an innduct is already
-running for that site.
+option to arrange that innduct silently exits if an instance is
+already running for that site.

 .SH INNDUCT VS INNFEED/NNTPSEND/INNXMIT
 .TP
 .B innfeed
 .SH INNDUCT VS INNFEED/NNTPSEND/INNXMIT
 .TP
 .B innfeed


@@ -71,15 +76,26 @@ feeding by looking in
 is the actual NNTP feeder program used by nntpsend.
 .SH GENERAL OPTIONS
 .TP
 is the actual NNTP feeder program used by nntpsend.
 .SH GENERAL OPTIONS
 .TP

-.BR \-f | \-\-feedfile= \fIfeedfile\fR
-Specifies
-.IR feedfile .
-If the specified value ends in a
+.BR \-f | \-\-feedfile= \fIpath\fR
+Specifies the
+.I feedfile
+to read, and indirectly specifies the paths to
+be used for various ancillary files (see FILES, below).
+If
+.I path
+ends in a

 .B /
 .B /

-it is taken as a directory to use as if it were
-.I pathoutgoing
-and the actual feed file used is
-.IR specified_feedfile / site .
+it is taken as a directory to use, and the actual feed file used is
+.IR path / site .
+If
+.I path
+does not start with a
+.BR / ,
+it is taken to be relative to
+.IR pathoutgoing
+from inn.conf.
+The default is
+.IR site .

 .TP
 .BR \-q | \-\-quiet-multiple
 Makes innduct silently exit (with status 0) if another innduct holds
 .TP
 .BR \-q | \-\-quiet-multiple
 Makes innduct silently exit (with status 0) if another innduct holds


@@ -88,7 +104,8 @@ be logged and a nonzero exit.
 .TP
 .BR \-\-no-daemon
 Do not daemonise.  innduct runs in the foreground and all messages
 .TP
 .BR \-\-no-daemon
 Do not daemonise.  innduct runs in the foreground and all messages

-(including all debug messages) are written to stderr.
+(including all debug messages) are written to stderr.  A control
+command line is also available on stdin/stdout.

 .TP
 .BI \-\-no-streaming
 Do not try to use the streaming extensions to NNTP (for use eg if the
 .TP
 .BI \-\-no-streaming
 Do not try to use the streaming extensions to NNTP (for use eg if the


@@ -106,26 +123,37 @@ Read
 instead of the default
 .BR inn.conf .
 .TP
 instead of the default
 .BR inn.conf .
 .TP

-.BR \-\-cli= \fIDIR\fR / |\fIPATH\fR
-Bind the control command line socket to
-.IB DIR / site _cli
-(if the value ends with a
-.BR /)
-or
-.I PATH
-(if it doesn't).  See CONTROLLING INNDUCT, below.
-This option may be essential, if the
-path to
-.I feedfile
-is too long, as there is a fairly short limit on the paths to AF_UNIX
-sockets.  The default is
-.IR feedfile \fB_cli\fR.  
-.TP

 .BI \-\-port= PORT
 Connect to port
 .I PORT
 at the remote site rather than to the NNTP port (119).
 .TP
 .BI \-\-port= PORT
 Connect to port
 .I PORT
 at the remote site rather than to the NNTP port (119).
 .TP

+.BI \-\-chdir= pathrun
+Change directory to
+.IR pathrun
+at startup.  The default is
+.I pathrun
+from inn.conf.
+.TP
+.BR \-\-cli= \fICLI-DIR\fR / |\fICLI-PATH\fR| none
+Listen for control command line connections on
+.IB CLI-DIR / site
+(if the value ends with a
+.BR /)
+or
+.I CLI-PATH
+(if it doesn't).  See CONTROLLING INNDUCT, below.
+Note that there is a fairly short limit on the paths to AF_UNIX
+sockets.  If specified as
+.IR CLI-DIR \fB/\fR,
+the directory will be created with mode 700 if necessary.
+The default is
+.B innduct/
+which means to create that directory in
+.I pathrun
+and listen on
+.RB \fIpathrun\fR /innduct/ \fIsite\fR.
+.TP

 .BI \-\-help
 Just print a brief usage message and list of the options to stdout.
 .SH TUNING OPTIONS
 .BI \-\-help
 Just print a brief usage message and list of the options to stdout.
 .SH TUNING OPTIONS


@@ -321,14 +349,14 @@ corrupted; you just won't see some of the article stats.
 .LP
 innduct listens on an AF_UNIX socket, and provides a command-line
 interface which can be used to trigger various events and for
 .LP
 innduct listens on an AF_UNIX socket, and provides a command-line
 interface which can be used to trigger various events and for

-debugging.  The socket is called
-.IB feedfile _cli
+debugging.  innduct listens (by default on
+.IR pathrun \fB/innduct/\fR site )

 and when connected reads and writes lines (with unix line endings).
 and when connected reads and writes lines (with unix line endings).

-It can most easily be accessed with a program like
+The cli can most easily be accessed with a program like

 .I netcat-openbsd
 (eg
 .I netcat-openbsd
 (eg

-.B nc.openbsd -U
-.IR feedfile \fB_cli\fR)
+.B nc.openbsd -U /var/run/news/innduct/
+.IR site )

 or
 .IR socat .
 The prompt is
 or
 .IR socat .
 The prompt is


@@ -424,6 +452,10 @@ 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"
 not mess with the feedfile and other associated files, other than as
 explained here:
 .IX Header "FILES"

+.IP \fIpathrun\fR
+.IX Item "default directory"
+Default current working directory for innduct, and also default
+parent directory for the command line socket.

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


@@ -485,7 +517,7 @@ safely remove backlog files.  \fIsomething\fR may not contain \fB#\fR
 you rename it to match the pattern \fIfeedfile\fR\fB_backlog\fR*, as
 otherwise innduct may find and process the file and read it to EOF
 before you have finished creating it.
 you rename it to match the pattern \fIfeedfile\fR\fB_backlog\fR*, as
 otherwise innduct may find and process the file and read it to EOF
 before you have finished creating it.

-.IP \fIfeedfile\fR_cli
+.IP \fIpathrun\fR\fB/innduct/\fB\fIsite\fR

 .IX Item "control command line socket"
 Default AF_UNIX listening socket for the control command line.  See
 CONTROLLING INNDUCT, above.
 .IX Item "control command line socket"
 Default AF_UNIX listening socket for the control command line.  See
 CONTROLLING INNDUCT, above.


@@ -495,10 +527,17 @@ On request via a control connection innduct dumps a summary of its
 state to this text file.  This is mostly useful for debugging.
 .IP /etc/news/inn.conf
 .IX Item inn.conf
 state to this text file.  This is mostly useful for debugging.
 .IP /etc/news/inn.conf
 .IX Item inn.conf

-Used to find
+Used for

 .IR pathoutgoing
 .IR pathoutgoing

-if none is specified, for finding how to communicate with innd,
-and also for
+(to compute default
+.IR feedfile
+and associated paths),
+.IR pathrun
+(to compute default
+.IR CLI-DIR
+and
+.IR CLI-PATH ),
+for finding how to communicate with innd, and also for

 .IR sourceaddress
 and/or
 .IR sourceaddress6 .
 .IR sourceaddress
 and/or
 .IR sourceaddress6 .