innfeed.conf (5)

DESCRIPTION

This man page describes the configuration file for version 1.0 of innfeed. This format has changed dramatically since version 0.9.3.

The file innfeed.conf is used to control the innfeed(1) program. It is a fairly free-format file that consists of three types of entries: key/value, peer and group. Comments are taken from the hash character ``#'' to the end of the line.

Key/value entries are a keyword and a value separated by a colon (which can itself be surrounded by whitespace). For example:

max-connections: 10

A legal key starts with a letter and contains only letters, numbers and ``_'', ``-''.

There are 5 different type of values: integers, floating-point numbers, characters, booleans, and strings. 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 ``true'' or ``false'' (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.

Peer entries look like:

peer <name> {
        # body ...
}

The word ``peer'' is required. The ``<name>'' is the same as the site name in INN's newsfeeds file. The body of a peer entry contains some number (possibly zero) of key/value entries.

Group entries look like:

group <name> {
        # body
}

The word ``group'' is required. The ``<name>'' is any string valid as a key. The body of a group entry contains any number of the three types of entries. So key/value pairs can be defined inside a group, and peers can be nested inside a group, and other groups can be nested inside a group.

Key/value entries that are defined outside of all peer and group entries are said to be at ``global scope''. There are global key/value entries that apply to the process as a whole (for example the location of the backlog file directory), and there are global key/value entries that act as defaults for peers. When innfeed 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 don't define the key/value, then the value at global scope is used.

A small example could be:

# 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 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 who 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's name.
        peer data.ramona.vix.com {
        }

        peer bb.home.vix.com {
                max-connections: 20     # he can really cook.
        }
}

Given the above configuration file, the defined peers would have the following values for the ``max-connections'' key.

uunet                  5
vixie                 10
data.ramona.vix.com   15
bb.home.vix.com       20

Innfeed ignores key/value pairs it is not interested in. Any config file value that can be set via a command line option, is not used if the command-line option is given.

Config files can be included in other config files via the syntax:

$INCLUDE filename

There is a maximum nesting depth of 10.

For a fuller example config file, see the supplied innfeed.conf.

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).

news-spool

This key requires a pathname value. It specifies where the top of the article spool is. This corresponds to the ``-a'' command-line option.

input-file

This key requires a pathname value. It specifies the pathname (relative to the backlog-directory) 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).

pid-file

This key requires a pathname value. It specifies the pathname (relative to the backlog-directory) where the pid of the innfeed process should be stored. This corresponds to the ``-p'' command-line option.

debug-level

This key defines the debug level for the process. A non-zero number generates a lot of messages to stderr, or to the config-defined ``log-file''. This corresponds to the ``-d'' command-line option.

use-mmap

This key requires a boolean value. It specifies whether mmaping should be used if innfeed has been built with mmap 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 false. This corresponds to the ``-M'' command-line option.

log-file

This key requires a pathname value. It specifies where any logging messages that couldn't be sent via syslog(3) should go (such as those generated when a positive value for ``debug-value'', is used). This corresponds to the ``-l'' command-line option. A relative pathname is relative to the ``backlog-directory'' value.