chiark / gitweb /
options for everything
[inn-innduct.git] / doc / man / innduct.8
index 87c602a..b71c2f8 100644 (file)
@@ -4,202 +4,170 @@ innduct \- quickly and reliably stream Usenet articles to remote site
 .SH SYNOPSIS
 .B innduct
 .RI [ options ]
-[
-.I sitename
-.I fqdn
-]
+.I site
+.RI [ fqdn ]
 .SH DESCRIPTION
-.I Innduct
-is a 
+.B innduct
+implements NNTP peer-to-peer news transmission including the streaming
+extensions, for sending news articles to a remote site.
 
-front-end that invokes
-.IR innxmit (1)
-to send Usenet articles to a remote NNTP site.
-.PP
-The sites to be fed may be specified by giving
-.I sitename
-.I fqdn
-pairs on the command line.
-If no such pairs are given,
-.I innduct
-defaults to the information given in the
-.I innduct.ctl
-config file.
-.PP
-The
-.I sitename
-should be the name of the site as specified in the
-.IR newsfeeds (5) 
-file.
-The 
-.I fqdn 
-should be the hostname or IP address of the remote site.
-.PP
-An
-.I innxmit
-is launched for sites with queued news.
-All
-.I innxmit
-processes are spawned in the background and the script waits for
-them all to finish before returning.
-Output is sent to the file
-.IR <pathlog\ in\ inn.conf>/innduct.log .
-In order to keep from overwhelming the local system, 
-.I innduct
-waits five seconds before spawning each child.
-.PP
-.I Innduct
-expects that the batchfile for a site is named
-.IR <pathoutgoing\ in\ inn.conf>/sitename .
-To prevent batchfile corruption,
-.IR shlock (1)
-is used to ``lock'' these files.
-.PP
-When
-.I sitename
+You need to run one instance of innduct for each peer site.  innduct
+manages its interaction with innd, including flushing the feed as
+appropriate, etc., so that articles are transmitted quickly, and
+manages the retransmission of its own backlog.  innduct includes the
+locking necessary to avoid multiple simutaneous invocations.
+
+By default, innduct reads the default feedfile corresponding to
+the site
+.I site
+(is
+.IR pathoutgoing / site )
+and feeds it via NNTP, streaming if possible, to the host
+.IR fqdn .
+
+If
 .I fqdn
-pairs are given on the command line, 
-any flags given on the command completely describe how
-.I innxmit
-and
-.I shrinkfile
-operate.
-When no such pairs are given on the command line, then
-the information found in
-.I innduct.ctl
-becomes the default flags for that site.
-Any flags given on the command line override the default flags
-for the site.
-.SH OPTIONS
+is not specified, it defaults to
+.IR site .
+
+Logging is sent to syslog.
+.SH GENERAL OPTIONS
+.TP
+.BR \-f | \-\-feedfile= \fIfeedfile\fR
+Specifies
+.IR feedfile .
+If the specified value ends in a
+.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 .
+.TP
+.BR \-q | \-\-quiet-multiple
+Makes innduct silently exit (with status 0) if another innduct holds
+the lock for the site.  Without \fB-q\fR, this causes a fatal error to
+be logged and a nonzero exit.
+.TP
+.BR \-\-no-daemon
+Do not daemonise.  innduct runs in the foreground and all messages
+(including all debug messages) are written to stderr.
+.TP
+.BI \-\-no-streaming
+Do not try to use the streaming extensions to NNTP (eg if the peer
+can't cope when we send MODE STREAM).
+.TP
+.BI \-\-inndconf= FILE
+Read
+.I FILE
+instead of the default
+.BR inn.conf .
+This is currently only used if
+.BI \-f feedfile
+is not specified, to find the value
+.I pathoutgoing
+for constructing the feedfile name from the site name.
+.TP
+.BI \-\-port= PORT
+Connect to port
+.I PORT
+at the remote site rather than to the NNTP port (119).
 .TP
-.B "\-d \-D"
-The ``\-d'' flag causes
-.I innduct
-to send output to stdout rather than the log file
-.IR <pathlog\ in\ inn.conf>/innduct.log .
-The ``\-D'' flag does the same
-and it passes ``\-d'' to all
-.I innxmit
-invocations, which in turn causes
-.I innxmit
-to go into debug mode.
+.BI \-\-help
+Just print a brief usage message and list of the options to stdout.
+.SH TUNING OPTIONS
+You should not normally need to adjust these.
 .TP
-.B -n
-If the ``\-n'' flag is used, then
-.I innduct
-does not use
-.IR shlock (1)
-and does not lock batch files.
+.BI \-\-max-connections= max
+Restricts the maximum number of simultaneous NNTP connections used by
+for each site to
+.IR max .
+The default is 10.  There is no global limit on the number of
+connections.
 .TP
-.B \-s size
-If the ``\-s'' flag is used, then
-.IR shrinkfile (1)
-will be invoked to perform a head truncation on the batchfile and the flag
-will be passed to it.
+.BI \-\-max-queue-per-conn= max
+Restricts the maximum number of outstanding articles queued on any
+particular connection
+.IR max .
+The default is 200.  (Non-streaming connections can only handle one
+article at a time.)
 .TP
-.B \-w delay
-If the ``\-w'' flag is used, then
-.I innduct
-waits for
-.I delay
-seconds after flushing the site before launching
-.IR innxmit .
+.BI \-\-feedfile-flush-size= bytes
+Specifies that innduct should flush when the feedfile size exceeds
+.IR bytes ;
+the effect is that the innduct will try to avoid the various
+batchfiles growing much beyond this size while the link to the peer is
+working.  The default is 100,000 bytes.
 .TP
-.B "\-a \-c \-l \-N \-P \-p \-r \-S \-T \-t"
-The ``\fB\-a\fP'', ``\fB\-c\fP'', ``\fB\-l\fP'', ``\fB\-P\fP'', ``\fB\-p\fP'',
-``\fB\-r\fP'', \``\fB\-S\fP'', ``\fB\-T\fP'' and ``\fB\-t\fP''
-flags are passed on to the child
-.I innxmit
-program. The ``\-N'' flag is passed as ``\fB\-s\fP'' flag to the child
-.I innxmit
-program.
-See 
-.IR innxmit (8)
-for more details.
-Note that if the ``\-p'' flag is used then no connection is made and
-no articles are fed to the remote site.
-It is useful to have
-.IR cron (8)
-invoke
-.I innduct
-with this flag in case a site cannot be reached for an extended period of time.
-.SH EXAMPLES
-With the following
-.IR innduct.ctl (5)
-control file:
-.PP
-.RS
-.nf
-nsavax:erehwon.nsavax.gov::-S -t60
-group70:group70.org::
-walldrug:walldrug.com:4m-1m:-T1800 -t300
-kremvax:kremvax.cis:2m:
-.fi
-.RE
-.PP
-The command:
-.PP
-.RS
-innduct
-.PP
-.RE
-will result in the following:
-.PP
-.RS
-.nf
-Sitename        Truncation      Innxmit flags
-nsavax          (none)          \-a \-S \-t60
-group70         (none)          \-a \-t180
-walldrug        1m if >4m       \-a \-T1800 \-t300
-kremvax         2m              \-a \-t180
-.fi
-.RE
-.PP
-The command:
-.PP
-.RS
-innduct \-d \-T1200
-.RE
-.PP
-will result in the following:
-.PP
-.RS
-.nf
-Sitename        Truncation      Innxmit flags
-nsavax          (none)          \-a \-d \-S \-T1200 \-t60
-group70         (none)          \-a \-d \-T1200 \-t180
-walldrug        1m if >4m       \-a \-d \-T1200 \-t300
-kremvax         2m              \-a \-d \-T1200 \-t180
-.fi
-.RE
-.PP
-The command:
-.PP
-.RS
-innduct \-s 5m \-T1200 nsavax erehwon.nsavax.gov group70 group70.org
-.PP
-.RE
-will result in the following:
-.PP
-.RS
-.nf
-Sitename        Truncation      Innxmit flags
-nsavax          5m              \-a \-T1200 \-t180
-group70         5m              \-a \-T1200 \-t180
-.fi
-.RE
-.PP
-Remember that ``\-a'' is always given, and ``\-t'' defaults to 180.
+.BI \-\-period-interval= PERIOD-INTERVAL
+Specifies wakup interval and period granularity.
+innduct wakes up every PERIOD-INTERVAL to do various housekeeping
+checks.  Also, many of the timeout and rescan intervals (those
+specified in this manual as
+.IR PERIOD s)
+are rounded up to the next multiple of PERIOD-INTERVAL.
+The default is one minute.
+.SH EXIT STATUS
+0 ok
+4 one is already running
+8 bad usage
+12 trouble
+.SH FILES
+.IX Header "FILES"
+.IP \fIpathoutgoing\fR/\fIsite\fR
+.IX Item "default feedfile"
+Default
+.IR feedfile .
+.IP \fIfeedfile\fR
+.IX Item feedfile
+Main feed file as specified in
+.IR newsfeeds (5).
+This and other batchfiles used by innduct contains lines each of which
+is of the form
+\&    \fItoken\fR \fImessageid\fR
+where \fItoken\fR is the inn storage API token.  Such lines can be
+written by \fBTf,Wnm\fR in a \fInewsfeeds\fR(5) entry.  During
+processing, innduct overwrites lines in the batch files which
+correspond to articles it has processed: the line is replaced with
+one containing only spaces.  Only innd should create this file, and
+only innduct should remove it.
+.IP \fIfeedfile\fR_lock
+.IX Item "lock file"
+Lockfile, preventing multiple innduct invocations for the same
+feed.  A process holds this lock after it has opened the lockfile,
+made an fcntl F_SETLK call, and then checked with stat and fstat that
+the file it now has open and has locked still has the name
+\fIfeedfile\fR_lock.  (Only) the lockholder may delete the lockfile.
+.IP \fIfeedfile\fR_flushing
+.IX Item "flushing file"
+Batch file: the main feedfile is renamed to this filename by innduct
+before it asks inn to flush the feed.  Only innduct should create or
+remove this file.
+.IP \fIfeedfile\fR_defer
+.IX Item "flushing file"
+Batch file containing details of articles whose transmission has
+recently been deferred at the request of the recipient site.  Created,
+written, read and removed by innduct.
+.IP \fIfeedfile\fR_backlog.\fItime_t\fR.\fIinum\fR
+.IX Item "backlog file"
+Batch file containing details of articles whose transmission has less
+recently been deferred at the request of the recipient site.  Created
+by innduct, and will also be read and removed by innduct.  However the
+administrator may also safely remove backlog files.
+.IP \fIfeedfile\fR_backlog\fIsomething\fR
+.IX Item "manual backlog file"
+Batch file manually provided by the administrator.  The file should be
+complete and ready to process at the time it is renamed or hardlinked
+to this name.  innduct will then automatically find and read and
+process it and eventually remove it.  The administrator may also
+safely remove backlog files.  \fIsomething\fR may not contain
+\fB#\fR \fB~\fR or \fB/\fR.
+.IP /etc/news/inn.conf
+.IX Item inn.conf
+Used to find
+.IR pathoutgoing
+if none is specified.
 .SH HISTORY
-Written by Landon Curt Noll <chongo@toad.com>
-and Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
-.de R$
-This is revision \\$3, dated \\$4.
-..
-.R$ $Id: innduct.8 5909 2002-12-03 05:17:18Z vinocur $
+Written by Ian Jackson <ijackson@chiark.greenend.org.uk>
 .SH "SEE ALSO"
 inn.conf(5),
-innxmit(1), 
-newsfeeds(5),
-innduct.ctl(5),
-shrinkfile(1).
+newsfeeds(5)