.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "INNFEED.CONF 5"
.TH INNFEED.CONF 5 2024-04-01 "INN 2.7.2" "InterNetNews Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
innfeed.conf \- Configuration file for innfeed
.SH "IN A NUTSHELL"
.IX Header "IN A NUTSHELL"
The \fIinnfeed.conf\fR file configures to which remote peers \fBinnfeed\fR sends
NNTP feeds.
.PP
A common entry to parameterize \f(CW\*(C`news.server.com\*(C'\fR as an outgoing feed is:
.PP
.Vb 3
\&    peer news.server.com {
\&        ip\-name: "news.server.com"
\&    }
.Ve
.PP
If standard NNTP port 119 is not used, you may specify an alternate port as
follows:
.PP
.Vb 4
\&    peer news.server.com {
\&        ip\-name: "news.server.com"
\&        port\-number: 433
\&    }
.Ve
.PP
After any changes, run \f(CW\*(C`inncheck\*(C'\fR to perform basic syntax checks, and
reload this configuration file with the following command which makes \fBinnd\fR
respawn a new instance of \fBinnfeed\fR (assuming \f(CW\*(C`innfeed!\*(C'\fR is the name of the
corresponding channel feed in \fInewsfeeds\fR):
.PP
.Vb 1
\&    ctlinnd flush innfeed!
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The configuration file \fIinnfeed.conf\fR in \fIpathetc\fR is used to control
the innfeed(8) program.  It is a fairly free-format file that consists
of three types of entries: \fIkey\fR:\fIvalue\fR, \fIpeer\fR and \fIgroup\fR.
Comments are from the hash character \f(CW\*(C`#\*(C'\fR to the end of the line.
.PP
\&\fIkey\fR:\fIvalue\fR entries are a keyword and a value separated by a colon
(which can itself be surrounded by whitespace).  For example:
.PP
.Vb 1
\&    max\-connections: 10
.Ve
.PP
A legal \fIkey\fR starts with a letter and contains only letters, digits,
and the \f(CW\*(C`_\*(C'\fR and \f(CW\*(C`\-\*(C'\fR characters.  There are 5 different types of values:
integers, floating-point numbers, characters, booleans, and strings.
.PP
Integer and floating-point numbers are as to be expected, except that
exponents in floating-point numbers are not supported.  A boolean value
is either \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`yes\*(C'\fR, \f(CW\*(C`on\*(C'\fR, \f(CW\*(C`false\*(C'\fR, \f(CW\*(C`no\*(C'\fR or \f(CW\*(C`off\*(C'\fR (case is not
significant).  A character value is a single-quoted character as defined by
the C\-language.  A string value is any other sequence of characters.  If the
string needs to contain whitespace, then it must be quoted with double quotes,
and uses the same format for embedding non-printing characters as normal
C\-language string.
.PP
Peer entries look like:
.PP
.Vb 3
\&    peer <name> {
\&        # body ...
\&    }
.Ve
.PP
The word \f(CW\*(C`peer\*(C'\fR is required.  The \fI<name>\fR is the same as the site
name in INN's \fInewsfeeds\fR configuration file.  The body of a peer entry
contains some number (possibly zero) of \fIkey\fR:\fIvalue\fR entries.
.PP
Group entries look like:
.PP
.Vb 3
\&    group <name> {
\&        # body ...
\&    }
.Ve
.PP
The word \f(CW\*(C`group\*(C'\fR is required.  The \fI<name>\fR is any string valid as
a key.  The body of a group entry contains any number of the three types of
entries.  So \fIkey\fR:\fIvalue\fR pairs can be defined inside a group, and peers
can be nested inside a group, and other groups can be nested inside a group.
.PP
\&\fIkey\fR:\fIvalue\fR entries that are defined outside of all \fIpeer\fR and \fIgroup\fR
entries are said to be at "global scope".  There are global \fIkey\fR:\fIvalue\fR
entries that apply to the process as a whole (for example the location of
the backlog file directory), and there are global \fIkey\fR:\fIvalue\fR entries
that act as defaults for peers.  When \fBinnfeed\fR looks for a specific value
in a peer entry (for example, the maximum number of connections to set up),
if the value is not defined in the peer entry, then the enclosing groups
are examined for the entry (starting at the closest enclosing group).
If there are no enclosing groups, or the enclosing groups do not define
the \fIkey\fR:\fIvalue\fR, then the value at global scope is used.
.PP
A small example could be:
.PP
.Vb 3
\&    # Global value applied to all peers that have
\&    # no value of their own.
\&    max\-connections: 5
\&
\&    # A peer definition.  "uunet" is the name used by innd
\&    # in the newsfeeds configuration file.
\&    peer uunet {
\&        ip\-name: usenet1.uu.net
\&    }
\&
\&    peer vixie {
\&        ip\-name: gw.home.vix.com
\&        max\-connections: 10       # Override global value.
\&    }
\&
\&    # A group of two peers which can handle more connections
\&    # than normal.
\&    group fast\-sites {
\&        max\-connections: 15
\&
\&        # Another peer.  The "max\-connections" value from the
\&        # "fast\-sites" group scope is used.  The "ip\-name" value
\&        # defaults to the peer\*(Aqs name.
\&        peer data.ramona.vix.com {
\&        }
\&
\&        peer bb.home.vix.com {
\&            max\-connections: 20   # He can really cook.
\&        }
\&    }
.Ve
.PP
Given the above configuration file, the defined peers would have the
following values for the \fImax-connections\fR key:
.PP
.Vb 4
\&    uunet                  5
\&    vixie                 10
\&    data.ramona.vix.com   15
\&    bb.home.vix.com       20
.Ve
.PP
\&\fBinnfeed\fR ignores \fIkey\fR:\fIvalue\fR pairs it is not interested in.
Some configuration file values can be set via a command-line option,
in which case that setting overrides the settings in the file.
.PP
Configuration files can be included in other configuration files via
the syntax:
.PP
.Vb 1
\&    $INCLUDE filename
.Ve
.PP
There is a maximum nesting depth of 10.
.PP
For a fuller example configuration file, see the supplied \fIinnfeed.conf\fR.
.SH "GLOBAL VALUES"
.IX Header "GLOBAL VALUES"
The following listing show all the keys that apply to the process as
whole.  These are not required (compiled-in defaults are used where needed).
.IP \fInews-spool\fR 4
.IX Item "news-spool"
This key requires a pathname value and defaults to \fIpatharticles\fR
in \fIinn.conf\fR.  It specifies where the top of the article spool is.
This corresponds to the \fB\-a\fR command-line option.
.IP \fIinput-file\fR 4
.IX Item "input-file"
This key requires a pathname value.  It specifies the pathname (relative to
the \fIbacklog-directory\fR value) that should be read in funnel-file mode.
This corresponds to giving a filename as an argument on the command-line
(i.e. its presence also implies that funnel-file mode should be used).
.Sp
The default is unset; \fBinnfeed\fR then runs in channel or batch mode.
.IP \fIpid-file\fR 4
.IX Item "pid-file"
This key requires a pathname value and defaults to \fIinnfeed.pid\fR.
It specifies the pathname (relative to \fIpathrun\fR in \fIinn.conf\fR)
where the pid of the \fBinnfeed\fR process should be stored.  This corresponds
to the \fB\-p\fR command-line option.
.IP \fIdebug-level\fR 4
.IX Item "debug-level"
This key defines the debug level for the process.  Default is \f(CW\*(C`0\*(C'\fR.
A non-zero number generates a lot of messages to stderr, or to the
config-defined \fIlog-file\fR.  This corresponds to the \fB\-d\fR command-line
option.
.Sp
If a file named \fIinnfeed.debug\fR exists in the \fIpathlog\fR directory (as
set in \fIinn.conf\fR), then \fIdebug-level\fR is automatically set to \f(CW\*(C`1\*(C'\fR.
This is a cheap way of avoiding continual reloading of the \fInewsfeeds\fR
file when debugging.  Note that debug messages still go to \fIlog-file\fR.
.IP \fIdebug-shrinking\fR 4
.IX Item "debug-shrinking"
This key requires a boolean value and defaults to false (the debug file is
allowed to grow without bound).  If set to true, this file is truncated when
its size reaches a certain limit.  See \fIbacklog-limit\fR for more details.
.IP \fIinitial-sleep\fR 4
.IX Item "initial-sleep"
This key requires a positive integer.  The default value is \f(CW\*(C`2\*(C'\fR.  It defines
the number of seconds to wait when \fBinnfeed\fR (or a fork) starts, before
beginning to open connections to remote hosts.
.IP \fIfast-exit\fR 4
.IX Item "fast-exit"
This key requires a boolean value and defaults to false.  If set to true,
when \fBinnfeed\fR receives a SIGTERM or SIGQUIT signal, it will close its
listeners as soon as it can, even if it means dropping articles.
.IP \fIuse-mmap\fR 4
.IX Item "use-mmap"
This key requires a boolean value and defaults to true.  When \fBinnfeed\fR
is given file names to send (a fairly rare use case) instead of storage
API tokens, it specifies whether mmaping should be used if \fBinnfeed\fR
has been built with mmap(2) support.  If article data on disk is not in
NNTP-ready format (CR/LF at the end of each line), then after mmaping,
the article is read into memory and fixed up, so mmaping has no positive
effect (and possibly some negative effect depending on your system),
and so in such a case this value should be \f(CW\*(C`false\*(C'\fR, which corresponds
to the \fB\-M\fR command-line option.
.IP \fIlog-file\fR 4
.IX Item "log-file"
This key requires a pathname value and defaults to \fIinnfeed.log\fR.
It specifies where any logging messages that could not be sent via syslog(3)
should go (such as those generated when a positive value for \fIdebug-level\fR
is used).  This corresponds to the \fB\-l\fR command-line option.
.Sp
This pathname is relative to \fIpathlog\fR in \fIinn.conf\fR.
.IP \fIlog-time-format\fR 4
.IX Item "log-time-format"
This key requires a format string suitable for strftime(3).  It is used
for messages sent via syslog(3) and to the \fIstatus-file\fR.  Default value
is \f(CW\*(C`%a %b %d %H:%M:%S %Y\*(C'\fR.
.IP \fIbacklog-directory\fR 4
.IX Item "backlog-directory"
This key requires a pathname value and defaults to \fIinnfeed\fR.  It specifies
where the current \fBinnfeed\fR process should store backlog files.
This corresponds to the \fB\-b\fR command-line option.
.Sp
This pathname is relative to \fIpathspool\fR in \fIinn.conf\fR.
.IP \fIbacklog-highwater\fR 4
.IX Item "backlog-highwater"
This key requires a positive integer value and defaults to \f(CW\*(C`5\*(C'\fR.
It specifies how many articles should be kept on the backlog file queue
before starting to write new entries to disk.
.IP \fIbacklog-ckpt-period\fR 4
.IX Item "backlog-ckpt-period"
This key requires a positive integer value and defaults to \f(CW\*(C`30\*(C'\fR.  It
specifies how many seconds elapse between checkpoints and rewrites of the
input backlog file.  Too small a number will mean frequent disk accesses;
too large a number will mean after a crash, \fBinnfeed\fR will re-offer more
already-processed articles than necessary.
.IP \fIbacklog-newfile-period\fR 4
.IX Item "backlog-newfile-period"
This key requires a positive integer value and defaults to \f(CW\*(C`600\*(C'\fR.
It specifies how many seconds elapse before each check for externally
generated backlog files that are to be picked up and processed.
.IP \fIbacklog-rotate-period\fR 4
.IX Item "backlog-rotate-period"
This key requires a positive integer value and defaults to \f(CW\*(C`60\*(C'\fR.
It specifies how many seconds elapse before \fBinnfeed\fR moves an externally
generated backlog file to the input backlog file (if \fIbacklog-newfile-period\fR
seconds have elapsed) or in the absence of such a file, moves the output
backlog file to the input backlog file.  No moves occur if the input backlog
file is not empty.
.IP \fIdns-retry\fR 4
.IX Item "dns-retry"
This key requires a positive integer value and defaults to \f(CW\*(C`900\*(C'\fR.
It defines the number of seconds between attempts to re-lookup host
information that previously failed to be resolved.
.IP \fIdns-expire\fR 4
.IX Item "dns-expire"
This key requires a positive integer value and defaults to \f(CW\*(C`86400\*(C'\fR.
It defines the number of seconds between refreshes of name to address
DNS translation.  This is so long-running processes do not get stuck with
stale data, should peer IP addresses change.
.IP \fIgen-html\fR 4
.IX Item "gen-html"
This key requires a boolean value and defaults to false.  It specifies
whether the \fIstatus-file\fR should be HTML-ified.
.IP \fIstatus-file\fR 4
.IX Item "status-file"
This key requires a pathname value and defaults to \fIinnfeed.status\fR.
An absolute pathname can be used.  It specifies the pathname (relative
to \fIpathhttp\fR when \fIgen-html\fR is true; otherwise, \fIpathlog\fR as set in
\&\fIinn.conf\fR) where the periodic status of the \fBinnfeed\fR process should
be stored.  This corresponds to the \fB\-S\fR command-line option.
.IP \fIconnection-stats\fR 4
.IX Item "connection-stats"
This key requires a boolean value and defaults to false.  If the value
is true, then whenever the transmission statistics for a peer are logged,
each active connection logs its own statistics.  This corresponds to the
\&\fB\-z\fR command-line option.
.IP \fIhost-queue-highwater\fR 4
.IX Item "host-queue-highwater"
This key requires a positive integer value and defaults to \f(CW\*(C`10\*(C'\fR.
It defines how many articles will be held internally for a peer before
new arrivals cause article information to be spooled to the backlog file.
.IP \fIstats-period\fR 4
.IX Item "stats-period"
This key requires a positive integer value and defaults to \f(CW\*(C`600\*(C'\fR.
It defines how many seconds \fBinnfeed\fR waits between generating statistics
on transfer rates.
.IP \fIstats-reset\fR 4
.IX Item "stats-reset"
This key requires a positive integer value and defaults to \f(CW\*(C`43200\*(C'\fR.
It defines how many seconds \fBinnfeed\fR waits before resetting all internal
transfer counters back to zero (after logging one final time).  This is
so a \fBinnfeed\fR process running more than a day will generate "final"
stats that will be picked up by logfile processing scripts.
.IP \fIinitial-reconnect-time\fR 4
.IX Item "initial-reconnect-time"
This key requires a positive integer value and defaults to \f(CW\*(C`30\*(C'\fR.
It defines how many seconds to first wait before retrying to reconnect
after a connection failure.  If the next attempt fails too, then the
reconnect time is approximately doubled until the connection succeeds,
or \fImax-reconnect-time\fR is reached.
.IP \fImax-reconnect-time\fR 4
.IX Item "max-reconnect-time"
This key requires an integer value and defaults to \f(CW\*(C`3600\*(C'\fR.  It defines
the maximum number of seconds to wait between attempt to reconnect
to a peer.  The initial value for reconnection attempts is defined by
\&\fIinitial-reconnect-time\fR, and it is doubled after each failure, up to
this value.
.IP \fIstdio-fdmax\fR 4
.IX Item "stdio-fdmax"
This key requires a non-negative integer value and defaults to \f(CW\*(C`0\*(C'\fR.
If the value is greater than zero, then whenever a network socket file
descriptor is created and it has a value \fIless than\fR this, the file
descriptor will be dup'ed to bring the value up greater than this.
This is to leave lower numbered file descriptors free for stdio.
Certain systems, Sun's in particular, require this.  SunOS 4.1.x usually
requires a value of \f(CW\*(C`128\*(C'\fR; 32\-bit Solaris versions or 32\-bit applications
running on 64\-bit Solaris, as well as 64\-bit Solaris versions prior to
11.0 require a value of \f(CW\*(C`256\*(C'\fR.  See the Solaris documentation about file
descriptors <https://support.oracle.com/knowledge/Sun%20Microsystems/1005979_1.html>
for more details.  The default if this is not specified, is \f(CW\*(C`0\*(C'\fR.
.SS "Special keys for \fBimapfeed\fP"
.IX Subsection "Special keys for imapfeed"
The following keys are used with \fBimapfeed\fR to authenticate to a remote
host.  Several parameters may be included at global scope:
.IP \fIdeliver-authname\fR 4
.IX Item "deliver-authname"
The authname is who you want to authenticate as.
.IP \fIdeliver-password\fR 4
.IX Item "deliver-password"
This is the appropriate password for authname.
.IP \fIdeliver-username\fR 4
.IX Item "deliver-username"
The username is who you want to "act" as, that is, who is actually going
to be using the server.
.IP \fIdeliver-realm\fR 4
.IX Item "deliver-realm"
In this case, the "realm" is the realm in which the specified authname
is valid.  Currently this is only needed by the DIGEST\-MD5 SASL mechanism.
.IP \fIdeliver-rcpt-to\fR 4
.IX Item "deliver-rcpt-to"
A printf(3)\-style format string for creating the envelope recipient address.
The pattern MUST include a single string specifier which will be replaced
with the newgroup (e.g. \f(CW\*(C`bb+%s\*(C'\fR).  The default is \f(CW\*(C`+%s\*(C'\fR.
.IP \fIdeliver-to-header\fR 4
.IX Item "deliver-to-header"
An optional printf(3)\-style format string for creating a To header field
to be prepended to the article.  The pattern MUST include a single string
specifier which will be replaced with the newgroup (e.g. \f(CW\*(C`post+%s@domain\*(C'\fR).
If not specified, the To header field will not be prepended.
.SH "GLOBAL PEER DEFAULTS"
.IX Header "GLOBAL PEER DEFAULTS"
All the \fIkey\fR:\fIvalue\fR pairs mentioned in this section can be specified at
global scope.  They may also be specified inside a group or peer definition.
Note that when peers are added dynamically (i.e. when \fBinnfeed\fR receives
an article for an unspecified peer), it will add the peer site using the
parameters specified at global scope.
.SS "Required keys"
.IX Subsection "Required keys"
No keys are currently required.  They all have a default value, if not
present in the configuration file.
.SS "Optional keys"
.IX Subsection "Optional keys"
The following keys are optional:
.IP \fIarticle-timeout\fR 4
.IX Item "article-timeout"
This key requires a non-negative integer value.  The default value is \f(CW\*(C`600\*(C'\fR.
If no articles need to be sent to the peer for this many seconds, then
the peer is considered idle and all its active connections are torn down.
.IP \fIresponse-timeout\fR 4
.IX Item "response-timeout"
This key requires a non-negative integer value.  The default value is \f(CW\*(C`300\*(C'\fR.
It defines the maximum amount of time to wait for a response from the peer
after issuing a command.
.IP \fIinitial-connections\fR 4
.IX Item "initial-connections"
This key requires a non-negative integer value.  The default value is \f(CW\*(C`1\*(C'\fR.
It defines the number of connections to be opened immediately when setting
up a peer binding.  A value of \f(CW\*(C`0\*(C'\fR means no connections will be created
until an article needs to be sent.
.IP \fImax-connections\fR 4
.IX Item "max-connections"
This key requires a positive integer value.  The default value is \f(CW\*(C`2\*(C'\fR but
may be increased if needed or for large feeds.  It defines the maximum
number of connections to run in parallel to the peer.  A value of \f(CW\*(C`0\*(C'\fR
specifies an unlimited number of maximum connections.  In general,
use of an unlimited number of maximum connections is not recommended.
Do not ever set \fImax-connections\fR to zero with \fIdynamic-method\fR 0 set,
as this will saturate peer hosts with connections.
.IP \fIclose-period\fR 4
.IX Item "close-period"
This key requires a positive integer value and defaults to \f(CW\*(C`86400\*(C'\fR.  It is
the maximum number of seconds a connection should be kept open.  Some NNTP
servers do not deal well with connections being held open for long periods.
.IP \fIdynamic-method\fR 4
.IX Item "dynamic-method"
This key requires an integer value between 0 and 3.  The default value is \f(CW\*(C`3\*(C'\fR.
It controls how connections are opened, up to the maximum specified by
\&\fImax-connections\fR.  In general (and specifically, with \fIdynamic-method\fR 0),
a new connection is opened when the current number of connections is below
\&\fImax-connections\fR, and an article is to be sent while no current connections
are idle.  Without further restraint (i.e. using \fIdynamic-method\fR 0), in
practice this means that \fImax-connections\fR connections are established
while articles are being sent.  Use of other \fIdynamic-method\fR settings
imposes a further limit on the amount of connections opened below that
specified by \fImax-connections\fR.  This limit is calculated in different
ways, depending of the value of \fIdynamic-method\fR.
.Sp
Users should note that adding additional connections is not always productive
\&\-\-\ just because opening twice as many connections results in a small
percentage increase of articles accepted by the remote peer, this may
be at considerable resource cost both locally and at the remote site,
whereas the remote site might well have received the extra articles sent
from another peer a fraction of a second later.  Opening large numbers of
connections is considered antisocial.
.Sp
The meanings of the various settings are:
.RS 4
.IP "\fB0\fR (no method)" 2
.IX Item "0 (no method)"
Increase of connections up to \fImax-connections\fR is unrestrained.
.IP "\fB1\fR (maximize articles per second)" 2
.IX Item "1 (maximize articles per second)"
Connections are increased (up to \fImax-connections\fR) and decreased so as
to maximize the number of articles per second sent, while using the fewest
connections to do this.
.IP "\fB2\fR (set target queue length)" 2
.IX Item "2 (set target queue length)"
Connections are increased (up to \fImax-connections\fR) and decreased
so as to keep the queue of articles to be sent within the bounds set
by \fIdynamic-backlog-low\fR and \fIdynamic-backlog-high\fR, while using the
minimum resources possible.  As the queue will tend to fill if the site is
not keeping up, this method ensures that the maximum number of articles
are offered to the peer while using the minimum number of connections to
achieve this.
.IP "\fB3\fR (combination)" 2
.IX Item "3 (combination)"
This method uses a combination of methods 1 and 2 above.  For sites accepting
a large percentage of articles, method 2 will be used to ensure these sites
are offered as complete a feed as possible.  For sites accepting a small
percentage of articles, method 1 is used, to minimize remote resource usage.
For intermediate sites, an appropriate combination is used.
.RE
.RS 4
.RE
.IP \fIdynamic-backlog-low\fR 4
.IX Item "dynamic-backlog-low"
This key requires a floating-point value between 0 and 100.  It represents
(as a percentage) the low water mark for the host queue.  If the host queue
falls below this level while using \fIdynamic-method\fR 2 or 3, and if 2 or
more connections are open, \fBinnfeed\fR will attempt to drop connections to
the host.  An Infinite Impulse Response (IIR) filter is applied to the
value to prevent connection flap (see \fIdynamic-filter\fR).  The default
value is \f(CW\*(C`20.0\*(C'\fR.  This value must be smaller than \fIdynamic-backlog-high\fR.
.IP \fIdynamic-backlog-high\fR 4
.IX Item "dynamic-backlog-high"
This key requires a floating-point value between 0 and 100.  It represents
(as a percentage) the high water mark for the host queue.  If the host
queue rises above this level while using \fIdynamic-method\fR 2 or 3, and
if less than \fImax-connections\fR are open to the host, \fBinnfeed\fR will
attempt to open further connections to the host.  An Infinite Impulse
Response (IIR) filter is applied to the value to prevent connection flap
(see \fIdynamic-filter\fR).  The default value is \f(CW\*(C`50.0\*(C'\fR.  This value must
be larger than \fIdynamic-backlog-low\fR.
.IP \fIdynamic-backlog-filter\fR 4
.IX Item "dynamic-backlog-filter"
This key requires a floating-point value between 0 and 1.  It represents
the filter coefficient used by the Infinite Impulse Response (IIR)
filter used to implement \fIdynamic-method\fR 2 and 3.  The default value
of this filter is \f(CW\*(C`0.7\*(C'\fR, giving a time constant of 1/(1\-0.7) articles.
Higher values will result in slower response to queue fullness changes;
lower values in faster response.
.IP \fImax-queue-size\fR 4
.IX Item "max-queue-size"
This key requires a positive integer value.  The default value is \f(CW\*(C`20\*(C'\fR.
It defines the maximum number of articles to process at one time when using
streaming to transmit to a peer.  Larger numbers mean more memory consumed as
articles usually get pulled into memory (see the description of \fIuse-mmap\fR).
.IP \fIstreaming\fR 4
.IX Item "streaming"
This key requires a boolean value.  Its default value is true.  It defines
whether streaming commands are used to transmit articles to the peers.
.IP \fIno-check-high\fR 4
.IX Item "no-check-high"
This key requires a floating-point number which must be in the range
[0.0, 100.0].  When running transmitting with the streaming commands,
\&\fBinnfeed\fR attempts an optimization called "no-CHECK mode".  This involves
\&\fInot\fR asking the peer if it wants the article, but just sending it.
This optimization occurs when the percentage of the articles the peer has
accepted gets larger than this number.  If this value is set to \f(CW\*(C`100.0\*(C'\fR,
then this effectively turns off no-CHECK mode, as the percentage can never
get above 100.0.  If this value is too small, then the number of articles
the peer rejects will get bigger (and your bandwidth will be wasted).
The default value of \f(CW\*(C`95.0\*(C'\fR usually works pretty well.
.IP \fIno-check-low\fR 4
.IX Item "no-check-low"
This key requires a floating-point number which must be in the range
[0.0, 100.0], and it must be smaller that the value for \fIno-check-high\fR.
When running in no-CHECK mode, as described above, if the percentage
of articles the remote server accepts drops below this number, then the
no-CHECK optimization is turned off until the percentage gets above the
\&\fIno-check-high\fR value again.  If there is small difference between this
and the \fIno-check-high\fR value (less than about 5.0), then \fBinnfeed\fR may
frequently go in and out of no-CHECK mode.  If the difference is too big,
then it will make it harder to get out of no-CHECK mode when necessary
(wasting bandwidth).  Keeping this to between 5.0 and 10.0 less than
\&\fBno-check-high\fR usually works pretty well.  The default value is \f(CW\*(C`90.0\*(C'\fR.
.IP \fIno-check-filter\fR 4
.IX Item "no-check-filter"
This is a floating-point value representing the time constant, in articles,
over which the CHECK/no\-CHECK calculations are done.  The default value is
\&\f(CW\*(C`50.0\*(C'\fR, which will implement an Infinite Impulse Response (IIR) filter
of time constant 50.  This roughly equates to making a decision about
the mode over the previous 50 articles.  A higher number will result in
a slower response to changing percentages of articles accepted; a lower
number will result in a faster response.
.IP \fIport-number\fR 4
.IX Item "port-number"
This key requires a positive integer value.  It defines the TCP/IP port
number to use when connecting to the remote.  Usually, port number 119
is used, which is the default value.
.IP \fIforce\-ipv4\fR 4
.IX Item "force-ipv4"
This key requires a boolean value.  By default, it is set to false.
Setting it to true is the same as setting \fIbindaddress6\fR to \f(CW\*(C`none\*(C'\fR
and removing \fIbindaddress\fR from \f(CW\*(C`none\*(C'\fR if it was set.
.IP \fIdrop-deferred\fR 4
.IX Item "drop-deferred"
This key requires a boolean value.  By default, it is set to false.
When set to true, and a peer replies with code 431 or 436 (try again later),
\&\fBinnfeed\fR just drops the article and does not try to re-send it.  This is
useful for some peers that keep on deferring articles for a long time to
prevent \fBinnfeed\fR from trying to offer the same article over and over again.
.IP \fImin-queue-connection\fR 4
.IX Item "min-queue-connection"
This key requires a boolean value.  By default, it is set to false.
When set to true, \fBinnfeed\fR will attempt to use a connection with the
least queue size (or the first empty connection).  If this key is set to
true, it is recommended that \fIdynamic-method\fR be set to \f(CW\*(C`0\*(C'\fR.  This allows
for article propagation with the least delay.
.IP \fIno-backlog\fR 4
.IX Item "no-backlog"
This key requires a boolean value.  It specifies whether spooling should
be enabled (false, the default) or disabled (true).  Note that when
\&\fIno-backlog\fR is set, articles reported as spooled are actually silently
discarded.
.IP \fIbacklog-limit\fR 4
.IX Item "backlog-limit"
This key requires a non-negative integer value.  If the number is \f(CW\*(C`0\*(C'\fR
(the default), then backlog files are allowed to grow without bound when the
peer is unable to keep up with the article flow.  If this number is greater
than 0, then it specifies the size (in bytes) the backlog file should get
truncated to when the backlog file reaches a certain limit.  The limit
depends on whether \fIbacklog-factor\fR or \fIbacklog-limit-highwater\fR is used.
.Sp
This parameter also applies to the debug file when \fIdebug-shrinking\fR
is set to true, and has the same effect on this file as the one has on
backlog files.
.IP \fIbacklog-factor\fR 4
.IX Item "backlog-factor"
This key requires a floating-point value, which must be larger than
1.0.  It is used in conjunction with the peer key \fIbacklog-limit\fR.
If \fIbacklog-limit\fR has a value greater than zero, then when the backlog
file gets larger than the value \fIbacklog-limit\fR * \fIbacklog-factor\fR,
then the backlog file will be truncated to the size \fIbacklog-limit\fR.
.Sp
For example, if \fIbacklog-limit\fR has a value of \f(CW\*(C`1000000\*(C'\fR, and
\&\fIbacklog-factor\fR has a value of \f(CW\*(C`2.0\*(C'\fR, then when the backlog file gets to
be larger than 2000000 bytes in size, it will be truncated to 1000000 bytes.
The front portion of the file is removed, and the trimming happens on
line boundaries, so the final size may be a bit less than this number.
If \fIbacklog-limit-highwater\fR is defined too, then \fIbacklog-factor\fR
takes precedence.  The default value of \fIbacklog-factor\fR is \f(CW\*(C`1.1\*(C'\fR.
.Sp
This parameter also applies to the debug file when \fIdebug-shrinking\fR
is set to true, and has the same effect on this file as the one has on
backlog files.
.IP \fIbacklog-limit-highwater\fR 4
.IX Item "backlog-limit-highwater"
This key requires a positive integer value that must be larger than the value
for \fIbacklog-limit\fR.  The default value is \f(CW\*(C`0\*(C'\fR.
.Sp
If the size of the backlog file gets larger than this value (in bytes),
then the backlog file will be shrunk down to the size of \fIbacklog-limit\fR.
If both \fIbacklog-factor\fR and \fIbacklog-limit-highwater\fR are defined,
then the value of \fIbacklog-factor\fR is used.
.Sp
This parameter also applies to the debug file when \fIdebug-shrinking\fR
is set to true, and has the same effect on this file as the one has on
backlog files.
.IP \fIbacklog-feed-first\fR 4
.IX Item "backlog-feed-first"
This key requires a boolean value.  By default it is set to false.  When set
to true, the backlog is fed before new files.  This is intended to enforce
in-order delivery, so setting this to true when \fIinitial-connections\fR
or \fImax-connections\fR is more than 1 is inconsistent.
.IP \fIbindaddress\fR 4
.IX Item "bindaddress"
This key requires a string value.  It specifies which outgoing IPv4 address
\&\fBinnfeed\fR should bind the local end of its connection to.  It must be an
IPv4 address in dotted-quad format (nnn.nnn.nnn.nnn), \f(CW\*(C`any\*(C'\fR, or \f(CW\*(C`none\*(C'\fR.
If not set or set to \f(CW\*(C`any\*(C'\fR, \fBinnfeed\fR defaults to letting the kernel
choose this address.  If set to \f(CW\*(C`none\*(C'\fR, \fBinnfeed\fR will not use IPv4 for
outgoing connections to peers in this scope (i.e. it forces IPv6).
.Sp
If not set in \fIinnfeed.conf\fR, \fBinnfeed\fR defaults to the value of
\&\fIsourceaddress\fR from \fIinn.conf\fR (which by default is unset).
.IP \fIbindaddress6\fR 4
.IX Item "bindaddress6"
This key requires a string value.  It behaves like \fIbindaddress\fR except
for outgoing IPv6 connections.  It must be in numeric IPv6 format (note
that a value containing colons must be enclosed in double quotes), \f(CW\*(C`any\*(C'\fR,
or \f(CW\*(C`none\*(C'\fR.  If set to \f(CW\*(C`none\*(C'\fR, \fBinnfeed\fR will not use IPv6 for outgoing
connections to peers in this scope.
.Sp
If not set in \fIinnfeed.conf\fR, \fBinnfeed\fR defaults to the value of
\&\fIsourceaddress6\fR from \fIinn.conf\fR (which by default is unset).
.IP \fIusername\fR 4
.IX Item "username"
This key requires a string value.  If the value is defined, then \fBinnfeed\fR
tries to authenticate by AUTHINFO USER and this value used for user name.
\&\fIpassword\fR must also be defined, if this key is defined.
.IP \fIpassword\fR 4
.IX Item "password"
This key requires a string value.  The value is the password used for
AUTHINFO PASS.  \fIusername\fR must also be defined, if this key is defined.
.SH "PEER VALUES"
.IX Header "PEER VALUES"
As previously explained, the peer definitions can contain redefinitions
of any of the \fIkey\fR:\fIvalue\fR pairs described in the section about global
peer defaults above.  There is one \fIkey\fR:\fIvalue\fR pair that is specific
to a peer definition.
.IP \fIip-name\fR 4
.IX Item "ip-name"
This key requires a word value.  The word is either one of the host's FQDNs,
or the dotted-quad IP address of the peer for IPv4, or the colon-separated
IP address of the peer for IPv6.  If this value is not specified, then
the name of the peer in the enclosing \fIpeer\fR block is taken to also
be its \fIip-name\fR.
.SH RELOADING
.IX Header "RELOADING"
If \fBinnfeed\fR gets a SIGHUP signal, then it will reread the configuration
file.  All values at global scope except for \fIbacklog-directory\fR can be
changed (although note that \fIbindaddress\fR and \fIbindaddress6\fR changes
will only affect new connections).
.PP
Any new peers are added and any missing peers have their connections closed.
.PP
The log file is also reopened.
.SH EXAMPLE
.IX Header "EXAMPLE"
For a comprehensive example, see the sample \fIinnfeed.conf\fR distributed
with INN and installed as a starting point.
.PP
Here are examples of how to format values:
.PP
.Vb 12
\&    eg\-string:         "New\etconfig\etfile\en"
\&    eg\-long\-string:    "A long string that goes
\&                       over multiple lines.  The
\&                       newline is kept in the
\&                       string except when quoted
\&                       with a backslash \e
\&                       as here."
\&    eg\-simple\-string:  A\-no\-quote\-string
\&    eg\-integer:        10
\&    eg\-boolean:        true
\&    eg\-char:           \*(Aqa\*(Aq
\&    eg\-ctrl\-g:         \*(Aq\e007\*(Aq
.Ve
.SH HISTORY
.IX Header "HISTORY"
Written by James Brister <brister@vix.com> for InterNetNews.  Converted to
POD by Julien Elie.
.PP
Earlier versions of \fBinnfeed\fR (up to 0.10.1) were shipped separately;
\&\fBinnfeed\fR is now part of INN and shares the same version number.
Please note that the \fIinnfeed.conf\fR format has changed dramatically since
version\ 0.9.3.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
inn.conf(5), innfeed(8), newsfeeds(5).