incrontab

title: incrontab(5)

text:
# incrontab(5)

## NAME
incrontab - tables for driving inotify cron (incron)

## DESCRIPTION
An incrontab file contains instructions to the incrond(8) daemon of the general form: "run this command on these file events". There are two categories of tables: system tables (with root privileges) and user tables (with user privileges).

System tables are (by default) located in /etc/incron.d and may have any names. Each system table exists separately inside incron and their watches never collide.

Each user has their own table, and commands in any given incrontab will be executed as the user who owns the incrontab. System users (such as apache, postfix, nobody etc.) may have their own incrontab.

incrontab files are read when the incrond(8) daemon starts and after any change (incrontab file are being hooked when incrond is running).

Blank lines are ignored. The general line format is the following:

<path> <mask> <command>

Where path is an absolute filesystem path, mask is an event mask (in symbolic or numeric form) and command is an executable file (or a script) with its arguments. See bellow for event mask symbols. The executable file may be noted as an absolute path or only as the name itself (PATH locations are examined).

Please remember that the same path may occur only once per table (otherwise only the first occurrence takes effect and an error message is emitted to the system log). Please not that the * wildcard is allowed to observe a range of files.

## EVENT SYMBOLS
These basic event mask symbols are defined:

IN_ACCESS File was accessed (read) (*)

IN_ATTRIB Metadata changed (permissions, timestamps, extended attributes, etc.) (*)

IN_CLOSE_WRITE File opened for writing was closed (*)

IN_CLOSE_NOWRITE File not opened for writing was closed (*)

IN_CREATE File/directory created in watched directory (*)

IN_DELETE File/directory deleted from watched directory (*)

IN_DELETE_SELF Watched file/directory was itself deleted

IN_MODIFY File was modified (*)

IN_MOVE_SELF Watched file/directory was itself moved

IN_MOVED_FROM File moved out of watched directory (*)

IN_MOVED_TO File moved into watched directory (*)

IN_OPEN File was opened (*)

When monitoring a directory, the events marked with an asterisk (*) above can occur for files in the directory, in which case the name field in the returned event data identifies the name of the file within the directory.

The IN_ALL_EVENTS symbol is defined as a bit mask of all of the above events. Two additional convenience symbols are IN_MOVE, which is a combination of IN_MOVED_FROM and IN_MOVED_TO, and IN_CLOSE which combines IN_CLOSE_WRITE and IN_CLOSE_NOWRITE.

The following further symbols can be specified in the mask:

IN_DONT_FOLLOW Don't dereference pathname if it is a symbolic link

IN_ONESHOT Monitor pathname for only one event

IN_ONLYDIR Only watch pathname if it is a directory

Additionally, there is a symbol which doesn't appear in the inotify symbol set. It is loopable=true. This symbol disables monitoring events until the current one is completely handled (until its child process exits). Also, there is the symbol recursive=false. This symbol limits the observation on the specified directory and does not include subdirectories. Finally, there is also the symbol dotdirs=true. This symbol will include the hidden directories (where the names starts with a dot) in the observation.

## WILDCARDS
The following wildards may be used inside command specification:

$$ dollar sign

$@ watched filesystem path (see above)

$# event-related file name

$% event flags (textually)

$& event flags (numerically)

## EXAMPLE
These are some example rules which can be used in an incrontab file:

/tmp IN_ALL_EVENTS abcd $@/$# $%

/usr/bin IN_ACCESS,loopable=true abcd $#

/home IN_CREATE /usr/local/bin/abcd $#

/home IN_CREATE,dotdirs=true /usr/local/bin/abcd $#

/home IN_CREATE,recursive=false /usr/local/bin/abcd $#

/var/log 12 abcd $@/$#

The first line monitors all events on the /tmp directory. When an event occurs it runs a application called 'abcd' with the full path of the file as the first arguments and the event flags as the second one.

The second line monitors accesses (readings) on the /usr/bin directory. The application 'abcd' is run as a handler and the appropriate event watch is disabled until the program finishes. The file name (without the directory path) is passed in as an argument.

The third example is used for monitoring the /home directory for newly create files or directories (it practically means an event is sent when a new user is added). This event is processed by a program specified by an absolute path.

The fourth example is the third example, but it will include hidden directories in the observation.

The fifth example is the third example, but it will exclude sub-directories from the observation.

And the final line shows how to use numeric event mask instead of textual one. The value 12 is exactly the same as IN_ATTRIB,IN_CLOSE_WRITE.

## SEE ALSO
incrond(8), incrontab(1), incron.conf(5)

## AUTHOR
Andreas Altair Redmer <altair.ibn.la.ahad.sy@gmail.com> (please report bugs to https://github.com/ar-/incron/issues ). Lukas Jelinek <lukas@aiken.cz> .

## COPYING
This program is free software. It can be used, redistributed and/or modified under the terms of the GNU General Public License, version 2.


info

package: info

title: info(5)

summary: readable online documentation

text:
# info(5)

## NAME
info - readable online documentation

## DESCRIPTION
The Info file format is an easily-parsable representation for online documents. It can be read by emacs(1) and info(1) among other programs.

Info files are usually created from texinfo(5) sources by makeinfo(1) , but can be created from scratch if so desired.

For a full description of the Texinfo language and associated tools, please see the Texinfo manual (written in Texinfo itself). Most likely, running this command from your shell:

```
info texinfo
```

or this key sequence from inside Emacs:

```
M-x info RET m texinfo RET
```

will get you there.

## AVAILABILITY
http://www.gnu.org/software/texinfo/

## REPORTING BUGS
Please send bug reports to bug-texinfo@gnu.org, general questions and discussion to help-texinfo@gnu.org.

## SEE ALSO
info(1), install-info(1), makeinfo(1), texi2dvi(1),

texindex(1).

emacs(1), tex(1).

texinfo(5).


active

package: inn

title: active(5)

text:
# active(5)

## NAME
active - List of newsgroups carried by the server

## DESCRIPTION
The file pathdb/active lists the newsgroups carried by INN. This file is generally maintained using ctlinnd(8) to create and remove groups, or by letting controlchan(8) do so on the basis of received control messages; this file is then updated and a backup stored in pathdb/active.old. Note that the newsgroups(5) file normally contains the descriptions of the newsgroups carried by the news server.

The active file should not be edited directly without throttling innd, and must be reloaded using ctlinnd before innd is unthrottled. Editing it directly even with those precautions may make it inconsistent with the overview database and won't update active.times, so ctlinnd should be used to make modifications whenever possible.

Each newsgroup should be listed only once. Each line specifies one group. The order of groups does not matter. Within each newsgroup, received articles for that group are assigned monotonically increasing numbers as unique names. If an article is posted to newsgroups not mentioned in this file, those newsgroups are ignored.

If none of the newsgroups listed in the Newsgroups header field body of an article are present in this file, the article is either rejected (if wanttrash is false in inn.conf), or is filed into the newsgroup "junk" and, when "Aj" is not set in the newsfeeds feed pattern, only propagated to sites that receive the "junk" newsgroup (if wanttrash is true).

Each line of this file consists of four fields separated by a space:

```
    <name> <high> <low> <status>
```

The first field is the name of the newsgroup. The newsgroup "junk" is special, as mentioned above. The newsgroup "control" and any newsgroups beginning with "control." are also special; control messages are filed into a control.* newsgroup named after the type of control message if that group exists, and otherwise are filed into the newsgroup "control" (without regard to what newsgroups are listed in the Newsgroups header field body). If mergetogroups is set to true in inn.conf, newsgroups that begin with "to." are also treated specially; see innd(8).

The second field is the highest article number that has been used in that newsgroup. The third field is the lowest article number in the group; this number is not guaranteed to be accurate, and should only be taken to be a hint. It is normally updated nightly as part of the expire process; see news.daily(8) and look for "lowmark" or "renumber" for more details. Note that because of article cancellations, there may be gaps in the numbering sequence. If the lowest article number is greater than the highest article number, then there are no articles in the newsgroup. In order to make it possible to update an entry in-place without rewriting the entire file, the second and third fields are padded out with leading zeros to make them a fixed width.

The fourth field contains one of the following status:

```
    y         Local postings and articles from peers are allowed.
    m         The group is moderated and all postings must be approved.
    n         No local postings are allowed, only articles from peers.
    j         Articles from peers are filed in the junk group instead.
    x         No local postings, and articles from peers are ignored.
    =foo.bar  Articles are filed in the group foo.bar instead.
```

If a newsgroup has the "j" status, no articles will be filed in that newsgroup. Local postings are not accepted; if an article for that newsgroup is received from a remote site, and if it is not crossposted to some other valid group, it will be filed into the "junk" newsgroup instead. This is different than simply not listing the group, since the article will still be accepted and can be propagated to other sites, and the "junk" group can be made available to readers if wished.

If the <status> field begins with an equal sign, the newsgroup is an alias. Articles cannot be posted to that newsgroup, but they can be received from other sites. Any articles received from peers for that newsgroup are treated as if they were actually posted to the group named after the equal sign. Note that the Newsgroups header field of the articles is not modified. (Alias groups are typically used during a transition and are typically created manually with ctlinnd(8).) An alias should not point to another alias.

Note that readers.conf can be configured so that local posts to newsgroups with status "j", "n" or "x" are accepted.

## MINIMAL ACTIVE FILE
For innd to be able to start, the three groups "control", "control.cancel" and "junk" need to be in the active file. Besides, if mergetogroups is set to true in inn.conf, the newsgroup "to" also needs to exist.

The minimal active file shipped with INN is:

```
    control 0000000000 0000000001 n
    control.cancel 0000000000 0000000001 n
    control.checkgroups 0000000000 0000000001 n
    control.newgroup 0000000000 0000000001 n
    control.rmgroup 0000000000 0000000001 n
    junk 0000000000 0000000001 n
```

(Note that the second and the third field may differ if the news server has already been in use.)

There are more control.* pseudogroups here than needed by innd to start; the corresponding control messages will be filed into them. The "n" status is so that users cannot post directly to these groups (control messages should only be posted to the groups that they affect). If you do not want these groups to be visible to clients, do not delete them but simply hide them in readers.conf(5).

To create additional groups after the server is running, you can use "ctlinnd newgroup". You can also synchronize your newsgroup list to that of another server by using actsync(8) or get the active file of another NNTP server with getlist(1). And do not forget to update your newsgroups file, which can be automatically done thanks to docheckgroups called with the -u flag.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
active.times(5), actsync(8), controlchan(8), ctlinnd(8), docheckgroups(8), getlist(1), inn.conf(5), innd(8), mod-active(8), news.daily(8), newsgroups(5), readers.conf(5).


active.times

title: active.times(5)

text:
# active.times(5)

## NAME
active.times - List of local creation times of newsgroups

## DESCRIPTION
The file pathdb/active.times provides a chronological record of when newsgroups were created on the local server. This file is normally updated by mod-active and innd whenever a newgroup control message is processed or a "ctlinnd newgroup" command is issued, and is used by nnrpd to answer NEWGROUPS requests.

Each line consists of three fields:

```
    <name> <time> <creator>
```

The first field is the name of the newsgroup. The second field is the time it was created, expressed as the number of seconds since the epoch. The third field is plain text intended to describe the entity that created the newsgroup. This field is encoded in UTF-8 and is usually the e-mail address of the person who created the group, as specified in the control message or on the ctlinnd command line, or the newsmaster specified at configure time if no creator argument was given to ctlinnd (by default, it is "usenet").

You can get the active.times file of another NNTP server with getlist(1).

## EXAMPLE
The line:

```
   news.admin.moderation 1175716803 <group-admin@isc.org>
```

shows that the newsgroup news.admin.moderation was created on April 4th, 2007, at 20:00:03 UTC. This date can be obtained for instance with "convdate -dc 1175716803" (convdate(1) is shipped with INN) or "date -u -d "Jan 1, 1970 00:00:00 +0000 + 1175716803 seconds"". It is when the newsgroup was locally created; in this example, it is when a control message sent by "group-admin@isc.org" was received and processed by the news server (see control.ctl(5) for more details). Therefore, the time is not necessarily the same on every news server.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
active(5), convdate(1), ctlinnd(8), getlist(1), inn.conf(5), innd(8), mod-active(8), nnrpd(8).


buffindexed.conf

title: buffindexed.conf(5)

text:
# buffindexed.conf(5)

## NAME
buffindexed.conf - Configuration for the buffindexed overview method

## DESCRIPTION
buffindexed.conf, found in pathetc, specifies the buffers that the buffindexed overview method should use. It is required if the server uses buffindexed (as configured by the ovmethod parameter in inn.conf).

Buffindexed uses pre-built buffer files to store overview data and indexes to that data. The buffers are divided into 8 KB internally, and a given block is used either for overview data or for index data. A block is always allocated to a single newsgroup and is never shared among newsgroups. It also means that overview data is limited to 8 KB per article, which may lead to the lack of integration of a few articles with headers of unusual length into the overview database.

In addition to the buffers, buffindexed also stores information in a file named group.index in pathdb. (This file should not be mistaken for the one named group.index in pathoverview which is used by the tradindexed overview method.) It contains information about each newsgroup: the pointer to the index block for the newsgroup, the high mark, the low mark, the flag of the group, the number of articles, and so forth. This file is created automatically when all buffers are initialized and should not be manually edited.

Buffindexed buffers are of fixed size, so buffindexed will never use more space than what is available in those buffers. If all buffers are full, innd will throttle when it attempts to store overview information for any additional articles until space is freed (with expireover, for instance) or another buffer is added. This is unlike the CNFS storage method.

You can see the current usage of the buffers with the -o option to inndf.

The overview data of received articles are flushed to disk every ovflushcount articles, as set in inn.conf.

In the buffindexed.conf file, blank lines and lines beginning with a number sign ("#") are ignored. All other lines must be of the format:

```
    <index>:<filename>:<size>
```

The order of lines is not significant.

<index> is the index of this overview buffer and must be unique. Other than that constraint, it can be any number between 0 and 65535.

<filename> is the path to the buffer. The length of the path should not be longer than 63 characters.

<size> is the length of the buffer in kilobytes (1 KB = 1024 bytes). If <filename> does not specify a special device, the file size of the buffer must be <size> * 1024 bytes. If it does specify a special device, that device must have at least <size> space available. For more information on setting up the buffers, see "CREATING BUFFERS".

An example of buffindexed.conf file can be:

```
    0:<pathoverview in inn.conf>/OV1:1536000
    1:<pathoverview in inn.conf>/OV2:1536000
```

When you first start innd with everything configured properly, you should see messages like this in pathlog/news.notice:

```
    Aug 27 00:00:00 kevlar innd: buffindexed: no magic cookie found
        for ovbuff 0, initializing
```

You MUST recreate overview completely using makehistory if you remove or replace buffers. However, new buffers can be added without any special care (other than restarting innd after modifying buffindexed.conf). If you need to rebuild overview, you should zero all of the buffers first.

We recommend not to reserve too much spare space in existing buffers, so that to minimize the duration of the expireover process, and to just add new buffers when space left is low (see the result of "inndf -no"). Plan on needing at least 0.65 KB for every article in your spool (not counting crossposts). So, if you have 5 million articles, you'll need at least 3.25 GB of disk space for buffindexed.

## CREATING BUFFERS
There are two methods to create a new buffindexed buffer:

1.

Create a large file on top of a regular file system. The easiest way to do this is probably with dd(1), using a command like:

```
    dd if=/dev/zero of=/path/to/cycbuff bs=1024 count=<size>

```

where <size> is the size from the relevant line in buffindexed.conf.

This is the simplest method, but has the disadvantage that very large files on regular file systems can be fairly slow to access, particularly at the end of the file, and INN incurs unnecessary file system overhead when accessing the buffer.

2.

Use block devices directly. If your operating system allows you to call mmap() on block devices (Solaris and recent versions of Linux do, FreeBSD at last report does not), this method can avoid all of the native file system overhead. Note, however, that Solaris has problems with byte range locking on block devices, and therefore this method should not be used on Solaris. Partition the disk. If you're using Solaris, set up your partitions to avoid the first cylinder of the disk (or otherwise the buffindexed header will overwrite the disk partition table and render the buffers inaccessible). Then, create device files for each block device you're going to use.

It's not recommended to use the block device files in /dev, since the news system doesn't have permission to write to them and changing the permissions of the system device files may affect something else. Instead, use mknod(1) to create a new set of block devices (in somewhere like pathspool/overview that's only writable by the news user). To do this, run "ls -Ll" on the devices in /dev that correspond to the block devices that you want to use. The major and minor device numbers are in the fifth and sixth columns (right before the date), respectively. Then run mknod like:

```
    mknod <filename> b <major> <minor>

```

where <filename> is the path to the device to create (matching the <filename> part of the buffindexed configuration line) and <major> and <minor> are the major and minor device numbers as discovered above.

Here's a short script to do this when given the path to the system device file as an argument:

```
    #!/bin/sh
    base=`echo "$1" | sed 's%.*/%%'`
    major=`ls -Ll "$1" | awk '{print $5}' | tr -d ,`
    minor=`ls -Ll "$1" | awk '{print $6}`
    mkdir -p <pathoverview in inn.conf>
    mknod <pathoverview>/"$base" b "$major" "$minor"
    chown news:news <pathoverview>/"$base"
    chmod 644 <pathoverview>/"$base"

```

Make sure that the created files are owned by the news user and news group, as specified at configure time (the default being "news" for both). Also make sure that the permissions on the devices allow the news user to read and write.

## HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
expireover(8), inn.conf(5), inndf(8), makehistory(8).


control.ctl

title: control.ctl(5)

text:
# control.ctl(5)

## NAME
control.ctl - Specify handling of Usenet control messages

## DESCRIPTION
The file pathetc/control.ctl is used to determine what action is taken when a control message is received. It is read by controlchan, which is normally invoked as a channel program by innd. When control.ctl is modified, controlchan notices this automatically and reloads it.

If a control.ctl.local file exists in pathetc, it is read by controlchan after control.ctl (the resulting behaviour is as though the contents of control.ctl.local were at the end of control.ctl). This local file is formatted like control.ctl and is intended to contain local customization. It is also automatically reloaded when modified.

Blank lines and lines beginning with a number sign ("#") are ignored. All other lines should consist of four fields separated by colons:

```
    <type>:<from>:<newsgroups>:<action>
```

Lines are matched in order and the last matching line in the file will be used, except for checkgroups messages which are handled differently (every matching line is used).

The first field, <type>, is the type of control message for which this line is valid. It should either be the name of a control message or the word "all" to indicate that it applies to all control messages. Besides, the following special types are understood:

/encoding/

This type specifies the encoding of newgroup and checkgroups control messages so that new descriptions could be decoded the right way.

```
    /encoding/:*:cn.*:gb18030

```

means that a description for a newsgroup in the Chinese cn.* hierarchy will be decoded as though it were encoded in GB18030, unless a charset is specified in the control message (in such a case, the charset mentioned in the message is used). However, it is possible to override the mentioned charset if "=force" is appended after the encoding. For instance,

```
    /encoding/:*:scout.forum.chinese:big5=force

```

means that the description for scout.forum.chinese will always be decoded as though it were encoded in Big5, no matter the charset of the corresponding control message.

The default value when no encoding is mentioned (or when the specified encoding is unknown) is "CP1252".

The last matching line for a given newsgroup name in control.ctl will be used.

/localencoding/

When this type is used, the line consist of only two fields. The default value when this type does not appear in control.ctl (or when the specified charset is unknown) is equivalent to:

```
    /localencoding/:utf-8

```

It means that new descriptions in the newsgroups file will be written using UTF-8. And controlchan will try to read existing descriptions, so as to see whether they should be updated, as though they were encoded in UTF-8.

The last matching line in control.ctl will be used.

/maxdocheckgroups/

This type specifies the maximum number of changes that could be made at one time by a checkgroups before bailing and mailing the changes to the admin if no log file was specified. The default value is 10.

```
    /maxdocheckgroups/:*:*:10
    /maxdocheckgroups/:*:fr.*:20

```

Such a configuration means that a checkgroups containing 15 changes for the French fr.* hierarchy (newgroups to add, remove or change the status) will be automatically honoured whereas a checkgroups containing 15 changes for france.* will only have the required changes mailed or logged.

The last matching line for a given newsgroup name in control.ctl will be used.

The second field, <from>, is a shell-style pattern that matches the e-mail address of the person posting the message (with the address first converted to lowercase). The matching is done with rules equivalent to those of the shell's case statement; see sh(1) for more details.

If the control message is a newgroup or rmgroup, the third field, <newsgroups>, is a shell-style pattern matching the newsgroup affected by the control message (especially "?" matches exactly one character, "*" matches zero or more characters and "|" permits matching several patterns on the same line -- for instance "comp.*|humanities.*" matches every newsgroup whose name begins with "comp." or "humanities."). If the control message is a checkgroups, the third field is a shell-style pattern matching the newsgroups that should be processed for checking. If the control message is of any other type, the third field is ignored.

The fourth field, <action>, specifies what action to take with control messages that match this line. The following actions are understood:

doit

The action requested by the control message should be performed. It means that the change will be silently performed. For checkgroups messages, depending on the value of /maxdocheckgroups/, the shell commands that should be run may be mailed to the news administrator (the argument to --with-news-master given at configure time, "usenet" by default) instead of being performed. If you always want notification of actions taken, use "doit=mail" instead (see below).

doit=file

The action is performed as in doit, and additionally a log entry is written to the specified log file file. If file is the word "mail", the log entry is mailed to the news administrator instead. An empty string is equivalent to /dev/null and says to log nothing. If file starts with a slash, it is taken as the absolute filename to use for the log file. Otherwise, the filename is formed by prepending pathlog and a slash, and appending ".log". In other words, an action of "doit=newgroup" will log to pathlog/newgroup.log.

drop

No action is taken and the message is ignored. For checkgroups messages, it means that the newsgroups mentioned will be considered as not existent in the checkgroups for its subsequent process.

```
    checkgroups:*:comp.*:doit
    checkgroups:*:*binaries*:drop

```

will for instance remove every newsgroup whose name contains "binaries" in the comp.* hierarchy, even though such groups are mentioned in the checkgroups. (In that example, the removal is performed by the doit action because drop does nothing by itself.)

verify-*

If the action starts with the string "verify-", as in:

```
    verify-news.announce.newgroups

```

then PGP verification of the control message will be done and the user ID of the key of the authenticated signer will be checked against the expected identity defined by the rest of the string ("news.announce.newgroups" in the above example). This verification is done via pgpverify; see pgpverify(1) for more details.

If no logging is specified (with =file as mentioned below), logging will be done the same as with doit as described above.

verify-*=mail

PGP verification is done as for the verify-* action described above, and notification of successful newgroup and rmgroup control messages and the output of checkgroups messages will be mailed to the news administrator. (In the case of checkgroups messages, this means that the shell script that should be run will be mailed to the administrator. The subject of the mail will contain information on whether the script has already been run, depending on the value of /maxdocheckgroups/.)

verify-*=file

PGP verification is done as for the verify-* action described above, and a log entry is written to the specified file as described in doit=file above. (In the case of checkgroups messages, this means that the shell script output of the checkgroups message will be written to that file. The initial line of the log will contain information on whether the script has already been run, depending on the value of /maxdocheckgroups/.)

log

A one-line log message is sent to standard error. innd normally directs this to pathlog/errlog.

log=file

A log entry is written to the specified log file, which is interpreted as in doit=file described above.

mail

A mail message is sent to the news administrator without taking any other action.

One of the difference between a doit or verify action and a mail action for a checkgroups control message lies in what e-mail is sent; doit or verify will mail the news administrator a shell script (which may have already been run) to create, delete, or modify newsgroups to match the checkgroups message, whereas mail will just mail relevant lines of the checkgroups for manual processing by the news administrator.

Use of the verify action for processing newgroup, rmgroup and checkgroups messages is STRONGLY recommended. Abuse of control messages is rampant, and authentication via PGP signature is currently the only reliable way to be sure that a control message comes from who it claims to be from. Most major hierarchies are now issuing PGP-authenticated control messages.

In order to use verify actions, the PGP key ring of the news user must be populated with the PGP keys of the hierarchy maintainers whose control messages you want to honour. For more details on PGP-authenticated control messages and the URL for downloading the PGP keys of major hierarchies, see pgpverify(1).

Control messages of type cancel are handled internally by innd and cannot be affected by any of the mechanisms described here.

## EXAMPLES
With the following three lines in control.ctl:

```
    newgroup:*:*:drop
    newgroup:group-admin@isc.org:comp.*:verify-news.announce.newgroups
    newgroup:kre@munnari.oz.au:aus.*:mail
```

a newgroup coming from "group-admin@isc.org" will be honoured if it is for a newsgroup in the comp.* hierarchy and if it has a valid signature corresponding to the PGP key with a user ID of "news.announce.newgroups". If any newgroup claiming to be from "kre@munnari.oz.au" for a newsgroup in the aus.* hierarchy is received, it too will be honoured. All other newgroup messages will be ignored.

Besides, if a control.ctl.local file exists and contains:

```
    newgroup:*:comp.lang.*:drop
```

then a newgroup control article for comp.lang.awk will not be honoured even though it comes from "group-admin@isc.org" with a valid signature.

As for checkgroups, suppose your news server contains these groups for foo.*, all of them being unmoderated ("y" status in the active file):

```
    foo.bar1
    foo.bar2.first
    foo.bar2.second
    foo.bar2.third
    foo.bar3
    foo.bar3.first
    foo.bar3.second
    foo.bar5
```

and you receive the following checkgroups by <foo@bar.com> for foo.*:

```
    foo.bar1          A valid newsgroup.
    foo.bar3.first    Only one newsgroup in foo.bar3.*.
    foo.bar4          A newsgroup you want.
    foo.bar5          A newsgroup you do not want.
    foo.bar5.first    Another newsgroup you do not want.
```

with the following control.ctl entries:

```
    /maxdocheckgroups/:*:foo.*:2
    checkgroups:foo@bar.com:foo.*:verify-key-foo
    checkgroups:foo@bar.com:foo.bar2.*:doit
    checkgroups:foo@bar.com:foo.bar3.*:mail
    checkgroups:foo@bar.com:foo.bar4|foo.bar4.*:doit
    checkgroups:foo@bar.com:foo.bar5|foo.bar5.*:drop
```

Then, as control.ctl is processed from bottom, here is what happens:

1.

The newsgroups foo.bar5 and foo.bar5.first are marked as unwanted. But nothing is done yet: other control.ctl entries have to be processed with a real action and a set of newsgroups containing foo.bar5 and foo.bar5.first.

2.

The newsgroup foo.bar4 is silently created on the news server, with the description "A newsgroup you want." added to the newsgroups file. In the absence of encoding values (either in the checkgroups message or in /encoding/ and /localencoding), the default is to decode the sentence as CP1242 and re-encode it as UTF-8. If "doit=mail" was used, a mail would be sent to the news administrator to inform him that foo.bar4 was successfully created.

3.

The newsgroup foo.bar3.second is no longer present. A mail is sent to the news administrator with a shell script to execute. When it is manually executed, foo.bar3.second will be removed. Note that the descriptions are handled differently and have already been updated without any manual intervention (foo.bar3.first now has the description "Only one newsgroup in foo.bar3.*." and foo.bar3.second no longer has a description).

4.

The newsgroups foo.bar2.first, foo.bar2.second and foo.bar2.third are no longer present. However, as the maximum number of changes that could be made at one time by a checkgroups before bailing and mailing the changes to the news administrator is 2, these newsgroups are not removed. A mail is sent with a shell script to manually execute in order to remove these groups from the news server. Note that their descriptions are removed from the newsgroups file, as well as any other possible descriptions for obsolete newsgroups in foo.bar2.*.

5.

The remaining entry is executed if the PGP verification of the checkgroups message is successful. Otherwise, nothing is done (especially, foo.bar5 remains on the news server). In case the PGP signature is verified, foo.bar3 and foo.bar5 are removed from the news server. This entry acts upon newsgroups marked as dropped in its scope and newsgroups not already dealt with by previous control.ctl entries (like foo.bar3 because only foo.bar3.* was previously checked).

Note that if you had wanted to keep foo.bar3 or foo.bar5, you could have added them to the localgroups file in pathetc.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten in POD by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
controlchan(8), inn.conf(5), innd(8), newsfeeds(5), newsgroups(5), pgpverify(1), sh(1).


cycbuff.conf

title: cycbuff.conf(5)

text:
# cycbuff.conf(5)

## NAME
cycbuff.conf - Configuration file for INN CNFS storage method

## DESCRIPTION
This file defines the cyclical buffers that make up the storage pools for CNFS (Cyclic News File System). Some options controlling the behavior of the CNFS storage system can also be set here. cycbuff.conf is required if the CNFS (Cyclic News File System) storage method is used. INN will look for it in pathetc (as set in inn.conf).

CNFS stores articles in logical objects called metacycbuffs. Each metacycbuff is in turn composed of one or more physical buffers called cycbuffs. As articles are written to the metacycbuff, each article is written to the next cycbuff in the list in a round-robin fashion (unless "sequential" mode is specified, in which case each cycbuff is filled before moving on to the next). This is so that you can distribute the individual cycbuffs across multiple physical disks and balance the load between them. Note that in order to use any cycbuff larger than 2 GB on 32-bit platforms (and some very rare 64-bit platforms that define a 32-bit off_t type), you need to build INN with the --enable-largefiles option.

For information about how to configure INN to use CNFS, see storage.conf(5).

Blank lines and lines beginning with a hash sign ("#") are ignored. All other lines must be of one of the following forms:

```
    cycbuffupdate:<interval>
    refreshinterval:<interval>
    cycbuff:<name>:<file>:<size>
    metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]
```

(where items enclosed in [] are optional). Order is mostly not significant, but all cycbuff lines must occur before all metacycbuff lines. Long lines can be continued on the next line by ending the line with a backslash ("\").

cycbuffupdate:<interval>

Sets the number of articles written before the cycbuff header is written back to disk to <interval>. Under most operating systems, the header doesn't have to be written to disk for the updated data to be available to other processes on the same system that are reading articles out of CNFS, but any accesses to the CNFS cycbuffs over NFS will only see the data present at the last write of the header. After a system crash, all updates since the last write of the CNFS header may be lost. The default value, if this line is omitted, is 25, meaning that the header is written to disk after every 25 articles stored in that cycbuff.

refreshinterval:<interval>

Sets the interval (in seconds) between re-reads of the cycbuff header to <interval>. This primarily affects nnrpd and controls the frequency with which it updates its knowledge of the current contents of the CNFS cycbuffs. The default value, if this line is omitted, is 30.

cycbuff:<name>:<file>:<size>

Configures a particular CNFS cycbuff. <name> is a symbolic name for the buffer, to be used later in a metacycbuff line. It must be no longer than seven characters. <file> is the full path to the buffer file or block device, and must be no longer than 63 characters. <size> is the length of the buffer in kilobytes (1 KB is 1024 bytes). If <file> is not a block device, it should be <size> * 1024 bytes long. If you're trying to stay under 2 GB, keep your sizes below 2097152.

Note that CNFSv4 supports files and partitions up to 16 TB.

metacycbuff:<name>:<buffer>[,<buffer>,...][:<mode>]

Specifies a collection of CNFS buffers that make up a single logical storage location from the perspective of INN. Metacycbuffs are referred to in storage.conf as storage locations for articles, so in order to actually put articles in a cycbuff, it has to be listed as part of some metacycbuff which is then referenced in storage.conf. <name> is the symbolic name of the metacycbuff, referred to in the options: field of "cnfs" entries in storage.conf. It must be no longer than eight characters. <buffer> is the name of a cycbuff (the <name> part of a cycbuff line), and any number of cycbuffs may be specified, separated by commas.

If there is more than one cycbuff in a metacycbuff, there are two ways that INN can distribute articles between the cycbuffs. The default mode, "INTERLEAVE", stores the articles in each cycbuff in a round-robin fashion, one article per cycbuff in the order listed. If the cycbuffs are of wildly different sizes, this can cause some of them to roll over much faster than others, and it may not give the best performance depending on your disk layout. The other storage mode, "SEQUENTIAL", instead writes to each cycbuff in turn until that cycbuff is full and then moves on to the next one, returning to the first and starting a new cycle when the last one is full. To specify a mode rather than leaving it at the default, add a colon and the mode ("INTERLEAVE" or "SEQUENTIAL") at the end of the metacycbuff line.

innd only reads cycbuff.conf on startup, so if you change anything in this file and want innd to pick up the changes, you have to use "ctlinnd xexec innd"; "ctlinnd reload all ''" is not sufficient.

When articles are stored, the cycbuff into which they're stored is saved as part of the article token. In order for INN to retrieve articles from a cycbuff, that cycbuff must be listed in cycbuff.conf. However, if INN should not write to a cycbuff, it doesn't need to be (and shouldn't be) listed in a metacycbuff.

This provides an easy way to retire a cycbuff. Just remove it from its metacycbuff, leaving in the cycbuff line, and restart innd (with, for example, "ctlinnd xexec innd"). No new articles will be put into the cycbuff, but neither will any articles expire from it. After you no longer need the articles in the cycbuff, just remove it entirely from cycbuff.conf. Then all of the articles will appear to have been deleted to INN, and the next nightly expire run will clean up any remaining references to them.

Adding a new cycbuff just requires creating it (see below), adding a cycbuff line, adding it to a metacycbuff, and then restarting innd. Similarly, changing the allocation of an existing cycbuff from a metacycbuff to another one just requires modifying the two metacycbuffs accordingly, and then restarting innd. (Only the cycbuff is noted noted in the storage API tokens.)

## CREATING CYCBUFFS
When creating a new cycbuff, there are two different methods for creating the buffers in which the articles will be stored.

1.

Create a large file on top of a regular file system. The easiest way to do this is probably with dd(1), using a command like:

```
    dd if=/dev/zero of=/path/to/cycbuff bs=1024 count=<size>

```

where <size> is the size from the cycbuff line in cycbuff.conf. INSTALL contains a script that will generate these commands for you from your cycbuff.conf file.

This is the simplest method, but has the disadvantage that very large files on regular file systems can be fairly slow to access, particularly at the end of the file, and INN incurs unnecessary file system overhead when accessing the cycbuff.

2.

Use block devices directly. If your operating system allows you to call mmap() on block devices (Solaris and recent versions of Linux do, FreeBSD at last report does not), this is the recommended method since you can avoid all of the native file system overhead. Note that some OSes do not support files larger than 2 GB, which will limit the size you can make a single cycbuff, but you can still combine many cycbuffs into each metacycbuff. Very old versions of Linux (before 2.4 kernels, that raised the limit to 2 TB) are known to have this limitation; FreeBSD does not. Some OSes that support large files don't support direct access to block devices for large partitions (Solaris prior to Solaris 7, or not running in 64-bit mode, is in this category); on those OSes, if you want cycbuffs over 2 GB, you'll have to use regular files. If in doubt, keep your cycbuffs smaller than 2 GB.

Partition the disk to make each partition equal to or smaller than 2 GB. If you're using Solaris, set up your partitions to avoid the first cylinder of the disk (or otherwise the cycbuff header will overwrite the disk partition table and render the cycbuffs inaccessible). Then, create device files for each block device you're going to use.

It's not recommended to use the block device files in /dev, since the news system doesn't have permission to write to them and changing the permissions of the system device files may affect something else. Instead, use mknod(1) to create a new set of block devices (in somewhere like pathspool/cycbuffs that's only writable by the news user). To do this, run "ls -Ll" on the devices in /dev that correspond to the block devices that you want to use. The major and minor device numbers are in the fifth and sixth columns (right before the date), respectively. Then run mknod like:

```
    mknod <file> b <major> <minor>

```

where <file> is the path to the device to create (matching the <file> part of the cycbuff line) and <major> and <minor> are the major and minor device numbers as discovered above.

Here's a short script to do this when given the path to the system device file as an argument:

```
    #!/bin/sh
    base=`echo "$1" | sed 's%.*/%%'`
    major=`ls -Ll "$1" | awk '{print $5}' | tr -d ,`
    minor=`ls -Ll "$1" | awk '{print $6}`
    mkdir -p <pathspool in inn.conf>/cycbuffs
    mknod <pathspool>/cycbuffs/"$base" b "$major" "$minor"
    chown news:news <pathspool>/cycbuffs/"$base"
    chmod 644 <pathspool>/cycbuffs/"$base"

```

Make sure that the created files are owned by the news user and news group, as specified at configure time (the default being "news" for both). Also make sure that the permissions on the devices allow the news user to read and write, and if you want other users on the system to be able to use sm to retrieve articles, make sure they're world-readable.

Once you have everything configured properly and you start innd, you should see messages in news.notice that look like:

```
    innd: CNFS: no magic cookie found for cycbuff ONE, initializing
```

where "ONE" will be whatever you called your cycbuff.

## HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. Rewritten into POD by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
ctlinnd(8), innd(8), nnrpd(8), sm(1), storage.conf(5).


distrib.pats

title: distrib.pats(5)

text:
# distrib.pats(5)

## NAME
distrib.pats - Default values for the Distribution header field

## DESCRIPTION
The file pathetc/distrib.pats is used by nnrpd to determine the default body of the Distribution header field. Blank lines and lines beginning with a number sign ("#") are ignored. All other lines consist of three fields separated by a colon:

```
    <weight>:<pattern>:<value>
```

The first field is the weight to assign to this match. If a newsgroup matches multiple lines, the line with the highest weight is used. This should be an arbitrary integer greater than zero. The order of lines in the file is only important if groups have equal weight (in which case, the first matching line will be used).

The second field is either the name of a newsgroup or a uwildmat-style pattern to specify a set of newsgroups.

The third field is the body that should be used for the Distribution header field of a posted article, if this line was picked as the best match and no Distribution header field was supplied by the user. It can be an empty string, specifying that no Distribution header field should be added. If it is not empty, it is better to only use US-ASCII characters for that field; otherwise, make sure it is encoded in UTF-8.

When a post is received by nnrpd that does not already contain a Distribution header field, each newsgroup to which an article is posted will be checked against this file in turn, and the matching line with the highest weight will be used as the body of the Distribution header field. If no lines match, or if the matching line has an empty string for its third field, no header field will be added. In case a distribution is added by nnrpd, make sure it is not rejected by the newsfeeds "ME" entry.

A list of recommended distributions can be specified and described in distributions(5).

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
distributions(5), inn.conf(5), libinn_uwildmat(3), newsfeeds(5), nnrpd(8).


distributions

title: distributions(5)

text:
# distributions(5)

## NAME
distributions - Recommended values for the Distribution header field

## DESCRIPTION
The file pathetc/distributions contains a list of relevant distributions and their descriptions. It provides local information for posters who wish to add a Distribution header field to their articles so as to restrict their propagation, although it does not guarantee that such articles will not leak elsewhere because of a misconfiguration of a news server to which they are fed. See newsfeeds(5) for more information about how a news server handles the Distribution header field.

Each line of this file consists of a distribution area followed by its description (encoded in UTF-8) after at least a whitespace. For instance:

```
    fr      Local to France.
    local   Local to this news server.
    nj      Local to New Jersey.
    usa     Local to the United States of America.
```

Blank lines and lines beginning with a number sign ("#") are ignored.

Any client that issues the LIST DISTRIBUTIONS command obtain these recommended values, if available. However, be aware that use of the LIST DISTRIBUTIONS command is not widespread (though documented in RFC 6048) and most news clients will never ask for this file.

If this file is empty, it is not an error. The server will just send the client an empty response. And if the file is missing, the server will also send the client an appropriate response to indicate that the distributions list is not maintained on the server.

The Distribution header field can also be automatically set by nnrpd if distrib.pats(5) is correctly configured.

## HISTORY
Written by Julien Elie for InterNetNews.

## SEE ALSO
distrib.pats(5), newsfeeds(5), nnrpd(8).


expire.ctl

title: expire.ctl(5)

text:
# expire.ctl(5)

## NAME
expire.ctl - Configuration file for article expiration

## DESCRIPTION
The file pathetc/expire.ctl is the default configuration file for expire and expireover, which read it at start-up. It serves two purposes: it defines how long history entries for expired or rejected articles are remembered, and it determines how long articles stored on the server are retained.

Normally, if all of the storage methods used by the server are self-expiring (such as CNFS), all lines except the "/remember/" setting (described below) are ignored. This can be changed with the -N option to expire or expireover.

Blank lines and lines beginning with a number sign ("#") are ignored. All other lines should be in one of two formats. The order of the file is significant, and the last matching entry will be used.

The first format specifies how long to keep history entries for articles that aren't present in the news spool. These are articles that have either already expired, or articles which the server rejected (when remembertrash is set to true in inn.conf). There should be one and only one line in this format, which looks like:

```
    /remember/:<days>
```

where <days> is a decimal number that specifies the minimum number of days a history record for a given Message-ID is retained (from its original posting time), regardless of whether the article is present in the spool. (History entries for articles still present in the spool are always retained.) Setting it to "never" means history records will be retained forever, 0 means history records for articles not present in the spool will be purged when expiry programs run. (This is notably useful in the case you need re-injecting articles no longer present in your news spool but considered as duplicate, because still present in history: you'll have to set "/remember/" to 0, run the expire process for instance via news.daily called with the same parameters as in crontab plus "notdaily", and undo the change in expire.ctl. All previously rejected or removed articles will then not be considered as duplicate if their Message-ID is proposed.)

The primary reason to retain a record of old articles is in case a peer offers old articles that were previously accepted but have already expired. Without a history record for such articles, the server would accept the article again and readers would see duplicate articles. Articles older than a certain number of days won't be accepted by the server at all (see artcutoff in inn.conf(5) and the -c flag in innd(8)), and this setting should probably match that time period to ensure that the server never accepts duplicates. As the default value for artcutoff is 10 days, it means that "/remember/" should be set to 11 days in order to take into account articles whose posting date is one day into the future.

Most of the lines in this file will be in the second format, which consists of either four or five colon-separated fields:

```
    <pattern>:<flag>:<min>:<default>:<max>
```

if groupbaseexpiry is true in inn.conf (the default), and otherwise:

```
    <classnum>:<min>:<default>:<max>
```

All lines must be in the correct format given the current setting of groupbaseexpiry, and therefore the two formats cannot co-exist in the same file.

Normally, a rule matches a newsgroup through the combination of the <pattern> and <flag> fields. <pattern> is a uwildmat-style pattern, specifying the newsgroups to which the line is applied. Note that the last matching entry will be used, so general patterns (such as defaults for all groups where <pattern> is "*") should appear at the beginning of the file before more specific settings.

The <flag> field can be used to further limit newsgroups to which the line applies, and should be chosen from the following set:

```
    M   Only moderated groups
    U   Only unmoderated groups
    A   All groups
    X   Remove the article from all groups it appears in
```

One of "M", "U", or "A" must be specified. "X" should be used in combination with one of the other letters, not by itself.

An expiration policy is applied to every article in a newsgroup it matches. There is no way to set an expiration policy for articles crossposted to groups you don't carry that's different than other articles in the same group. Normally, articles are not completely deleted until they expire out of every group to which they were posted, but if an article is expired following a rule where <flag> contains "X", it is deleted out of all newsgroups to which it was posted immediately. (If that behaviour is wanted for all rules, you may want to give the -e flag to expireoverview.)

If groupbaseexpiry is instead set to false, there is no <pattern> and <flag> field and the above does not apply. Instead, there is a single <classnum> field, which is either a number matching the storage class number specified in storage.conf or "*" to specify a default for all storage classes. All articles stored in a storage class will be expired following the instructions in the line with a matching <classnum>, and when articles are expired, they're always removed from all groups to which they were posted.

The remaining three fields are the same in either format, and are used to determine how long an article should be kept from its original arrival time (unless the -p flag is passed to expire(8) or expireover(8), in which case its original posting time is used). Each field should be either a decimal number of days (fractions like 8.5 are allowed, but remember that articles are only removed when expire or expireover is run, normally once a day by news.daily) or the word "never".

The middle field, <default>, will be used as the expiration period for most articles. The other two fields, <min> and <max>, only come into play if the article requests a particular expiration date with an Expires header field. Articles with an Expires header field will be expired at the date given in that header field, subject to the constraints that they will be retained at least <min> days and no longer than <max> days.

If <min> is set to "never", no article matching that line will ever be expired. If <default> is set to "never", no article matching that line without an explicit Expires header field will ever be expired. If <max> is set to "never", Expires header fields will be honored no matter how far into the future they are.

One should think of the fields as a lower bound, the default, and an upper bound. Since most articles do not have an Expires header field, the second field is the most important and most commonly applied.

Articles that do not match any expiration rule will not be expired, but this is considered an error and will result in a warning. There should always be a default line (a line with a <pattern> of "*" and <flag> of "A", or a line with a <classnum> of "*"), which can explicitly state that articles should never expire by default if that's the desired configuration. The default line should generally be the first line of the file (except for "/remember/") so that other expiration rules can override it.

It is often useful to honor the Expires header field in articles, especially those in moderated groups. To do this, set <min> to zero, <default> to whatever normal expiration you wish, and <max> to "never" or some large number, like 365 days for a maximum article life of a year.

To ignore any Expires header field, set all three fields to the same value.

## EXAMPLES
When groupbaseexpiry is true (the default):

```
    # Keep expired article history for 11 days, matching artcutoff
    # plus one.
    /remember/:11
    # Most articles stay for two weeks, ignoring Expires header fields.
    *:A:14:14:14
    # Accept Expires header fields in moderated newsgroups for up to
    # a year, and retain moderated newsgroups for a bit longer.
    *:M:1:30:365
    # Keep local newsgroups for a long time and local project
    # newsgroups forever.
    example.*:A:1:90:90
    example.project.*:A:never:never:never
```

When groupbaseexpiry is false, for class-based expiration:

```
    # Keep expired article history for 11 days, matching artcutoff
    # plus one.
    /remember/:11
    # Set a default expiration of seven days and honour Expires header
    # fields within reasonable limits.
    *:1:7:35
    # Class 0 is retained for two weeks and honor Expires header fields
    # within reasonable limits.
    0:1:14:65
```

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
expire(8), expireover(8), inn.conf(5), innd(8), libinn_uwildmat(3), news.daily(8), storage.conf(5).


history

title: history(5)

text:
# history(5)

## NAME
history - Record of current and recently expired Usenet articles

## DESCRIPTION
The file pathdb/history keeps a record of all articles currently stored in the news system, as well as those that have been received but since expired. In a typical production environment, this file will be many megabytes.

The file consists of text lines. Each line corresponds to one article. The file is normally kept sorted in the order in which articles are received, although this is not a requirement. innd appends a new line each time it files an article, and expire builds a new version of the file by removing old articles and purging old entries.

Each line consists of two or three fields separated by a tab, shown below as " \t ":

```
    [hash] \t date
    [hash] \t date \t @token@
```

The hash field is the ASCII representation of the hash of the Message-ID. This is directly used for the key of the dbz.

The date field consists of three sub-fields separated by a tilde. All sub-fields are the text representation of the number of seconds since the epoch, that is to say a time_t like in gettimeofday(2). The first sub-field is the article's arrival date. If copies of the article are still present, then the second sub-field is either the value of the article's Expires header field, or a hyphen if no expiration date was specified. If an article has been expired, then the second sub-field will be a hyphen. The third sub-field is the value of the article's Date header field, recording when the article was posted.

The token field is a token of the article. This field is empty if the article has been expired.

For example, an article whose Message-ID was <7q2saq$sal$1@isrv4.pa.vix.com>, posted on 26 Aug 1999 08:02:34 GMT and received at 26 Aug 1999 08:06:54 GMT, could have a history line (broken into three lines for display) like the following:

```
    [E6184A5BC2898A35A3140B149DE91D5C] \t
        935678987~-~935678821 \t
        @030154574F00000000000007CE3B000004BA@
```

In addition to the text file, there is a dbz database associated with the file that uses the Message-ID field as a key to determine the offset in the text file where the associated line begins. For historical reasons, the key includes the trailing "\0" byte (which is not stored in the text file).

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten into POD by Julien Elie.

## SEE ALSO
expire(8), inn.conf(5), innd(8), libinn_dbz(3), makehistory(8).


incoming.conf

title: incoming.conf(5)

summary: Configuration of incoming news feeds

text:
# incoming.conf(5)

## NAME
incoming.conf - Configuration of incoming news feeds

## IN A NUTSHELL
The incoming.conf file configures from which remote peers innd accepts NNTP feeds.

A common entry to allow "news.server.com" as an incoming peer is:

```
    peer news.server.com {
        hostname: "news.server.com"
    }
```

The port used for incoming feeds is the one innd is listening on (usually port 119 or 433).

Peer entries are read in the order they appear in the configuration file. The first peer entry with a hostname value matching the incoming connection will be used to grant access to the remote peer. Subsequent entries will be discarded.

After any changes, run "inncheck" to perform basic syntax checks, and reload this configuration file with the following command:

```
    ctlinnd reload incoming.conf 'new peer'
```

## DESCRIPTION
The file pathetc/incoming.conf consists of three types of entries: key/value, peer and group. Comments are from the hash character "#" to the end of the line. Blank lines are ignored. All key/value entries within each type must not be duplicated. Key/value entries are a keyword immediately followed by a colon, at least one blank and a value. For example:

```
    max-connections: 10
```

A legal key does not contains blanks, colons, nor "#". There are three different types of values: integers, booleans, and strings. Integers are as to be expected. A boolean value is either "true", "yes", "on", "false", "no" or "off" (case is not significant). A string value is any other sequence of characters. If the string needs to contain whitespace, then it must be quoted with double quotes.

Peer entries look like:

```
    peer <name> {
        # body
    }
```

The word "peer" is required. <name> is a label for this peer. It is any string valid as a key. The body of a peer entry contains some number of key/value entries.

Group entries look like:

```
    group <name> {
        # body
    }
```

The word "group" is required. <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. Global key/value entries act as defaults for peers. When innd looks for a specific value in a peer entry (for example, the maximum number of connections to allow), 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.
    peer uunet {
        hostname: usenet1.uu.net
    }
    peer vixie {
        hostname: gw.home.vix.com
        max-connections: 10        # Override global value.
    }
    # A group of two peers which can open more connections than normal.
    group fast-sites {
        max-connections: 15
        # Another peer.  The max-connections value from the
        # fast-sites group scope is used.
        peer data.ramona.vix.com {
            hostname: data.ramona.vix.com
        }
        peer bb.home.vix.com {
            hostname: 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
```

## PARAMETERS
The following keys are allowed:

hold-time

This key requires a positive integer value. It defines the hold time before closing, if the connection is over max-connections. A value of zero specifies immediate close. The default is 0.

hostname

This key requires a string value. It is a list of hostnames separated by a comma. A hostname is either a fully qualified domain name that resolves to the IPv4 or IPv6 address of the peer, or the dotted-quad IP address of the peer for IPv4, or the colon-separated IP address of the peer for IPv6. If this key is not present in a peer block, the hostname defaults to the label of the peer.

identd

This key requires a string value. It is used if you wish to require a peer's user name retrieved through identd(8) match the specified string. Note that currently innd does not implement any timeout in identd callbacks, so enabling this option may cause innd to hang if the remote peer does not respond to ident callbacks in a reasonable timeframe. The default is an empty string, that is to say no ident daemon.

ignore

This key requires a boolean value. Setting this entry to true causes innd to answer negatively to proposals from the remote peer to send you articles. The default is false. More technically, if ignore is true, innd will refuse every Message-ID proposed to be sent via CHECK or IHAVE by this peer, thus behaving as though it already has the article. A complete article sent by this peer via TAKETHIS (because it does not first query with CHECK, or it does not take into account the refusal response code from a previous CHECK) will still be accepted.

list

This key requires a boolean value. It defines whether a peer is allowed to issue LIST commands. The default is true, that is to say it can.

max-connections

This key requires a positive integer value. It defines the maximum number of connections allowed. A value of zero specifies an unlimited number of maximum connections ("unlimited" or "none" can be used as synonyms). The default is 0.

password

This key requires a string value. It is used if you wish to require a peer to supply a password via AUTHINFO USER/PASS. The default is an empty string, that it to say no password is expected. Note that innd will accept any username provided by the remote peer as long as the password corresponds. (As the username is mandatory in the authentication protocol, innd expects one but does nothing with it.)

patterns

This key requires a string value. It is a list of newsfeeds(5)-style list of newsgroups which are to be accepted from this host. The default is the string "*", that is to say all groups are accepted.

resendid

This key requires a boolean value. When set to true, innd asks the remote peer to retry later to send the proposed article (which happens when another peer has already offered to send it, but has not yet), using 431 (response to CHECK, in streaming mode) or 436 (response to IHAVE in non-streaming mode) codes. When set to false, innd does not ask any new attempt (which will lead to the loss of an article in case the other peer does not send it), using 438 (response to CHECK) or 435 (response to IHAVE) codes. The deferral feature can be useful for peers that resend messages right away, as innfeed does. The default is true: the deferral feature is used so that the peer receives 431 and 436 codes, and therefore resends the article later.

skip

This key requires a boolean value. Setting this entry causes this peer to be skipped. The default is false.

streaming

This key requires a boolean value. It defines whether streaming commands (CHECK and TAKETHIS) are allowed from this peer. The default is true.

xbatch

This key requires a boolean value. It defines whether a peer is allowed to issue XBATCH commands. The default is false, that is to say it cannot.

## HISTORY
Written by Fabien Tassin <fta@sofaraway.org> for InterNetNews. Converted to POD by Julien Elie.

## SEE ALSO
inn.conf(5), innd(8), libinn_uwildmat(3), newsfeeds(5).


inn-radius.conf

title: inn-radius.conf(5)

text:
# inn-radius.conf(5)

## NAME
inn-radius.conf - Configuration for nnrpd RADIUS authenticator

## DESCRIPTION
This describes the format and attributes of the configuration file for the nnrpd RADIUS authenticator. See radius(8) for more information about the authenticator program. The default location for this file is inn-radius.conf in pathetc.

Blank lines and lines beginning with "#" are ignored, as is anything after a "#" on a line. All other lines should begin with a parameter name followed by a colon and the value of that key, except that each section of configuration for a particular server should be enclosed in:

```
    server <name> {
        # parameters...
    }
```

where <name> is just some convenient label for that server.

## SERVER GROUP PARAMETERS
The available parameters are:

radhost

The hostname of the RADIUS server to use for authentication. This parameter must be set.

radport

The port to query on the RADIUS server. Defaults to 1645 if not set.

lochost

The hostname or IP address making the request. The RADIUS server expects an IP address; a hostname will be translated into an IP address with gethostbyname(). If not given, this information isn't included in the request (not all RADIUS setups require this information).

locport

The port the client being authenticated is connecting to. If not given, defaults to 119. This doesn't need to be set unless readers are connecting to a non-standard port.

secret

The shared secret with the RADIUS server. If your secret includes spaces, tabs, or "#", be sure to include it in double quotes. This parameter must be set.

prefix

Prepend the value of this parameter to all usernames before passing them to the RADIUS server. Can be used to prepend something like "news-" to all usernames in order to put news users into a different namespace from other accounts served by the same server. If not set, nothing is prepended.

suffix

Append the value of this parameter to all usernames before passing them to the RADIUS server. This is often something like "@example.com", depending on how your RADIUS server is set up. If not set, nothing is appended.

ignore-source

Can be set to "true", "yes", "on", "false", "no" or "off". If set to false, the RADIUS authenticator will check to ensure that the response it receives is from the same IP address as it sent the request to (for some added security). If set to true, it will skip this verification check (if your RADIUS server has multiple IP addresses or if other odd things are going on, it may be perfectly normal for the response to come from a different IP address).

## EXAMPLE
Here is a configuration for a news server named news.example.com, authenticating users against radius.example.com and appending "@example.com" to all client-supplied usernames before passing them to the RADIUS server:

```
    server example {
        radhost: radius.example.com
        lochost: news.example.com
        secret: IamARADIUSsecRET
        suffix: @example.com
    }
```

The shared secret with the RADIUS server is "IamARADIUSsecRET".

## HISTORY
This documentation was written by Russ Allbery <eagle@eyrie.org> based on the comments in the sample inn-radius.conf file by Yury B. Razbegin.

## SEE ALSO
radius(8).


inn-secrets.conf

title: inn-secrets.conf(5)

text:
# inn-secrets.conf(5)

## NAME
inn-secrets.conf - Configuration data for InterNetNews secrets

## DESCRIPTION
inn-secrets.conf in pathetc is a configuration file containing general secrets used by INN. It was added in INN 2.7.0 for the implementation of Cancel-Lock. The intent is that new secrets used by INN are added to that file, and that all secrets currently stored in several other configuration files eventually move to that file.

The inn-secrets.conf file is not required. It currently only serves the purpose of Cancel-Lock. If not present or empty, the Cancel-Lock authentication system will just be deactivated for local posts.

This file is intended to be fairly static. Any changes made to it will generally not affect any running programs until they restart.

Changes in Cancel-Lock secrets will be taken into account when new nnrpd processes are spawned (which happens each time a reader opens a new connection).

Blank lines and lines starting with a number sign ("#") are ignored. All other lines specify parameters, and are organized in groups. The general form is:

```
    <group> {
        <parameter>: <value>
    }
```

(Any amount of whitespace can be put after the colon and is optional.) If the value contains embedded whitespace or any of the characters "[]<>{}"\:;", it must be enclosed in double quotes (""). A backslash ("\") can be used to escape quotes and backslashes inside double quotes. <group> and <parameter> are case-sensitive; "cancels" is not the same as "Cancels" or "CANCELS". (inn-secrets.conf groups and parameters are generally all in lowercase.)

The two parameters currently defined in this file have as their value a list of strings, that is to say space-separated elements enclosed in square brackets. Examples follow in the documentation.

## PARAMETERS

### Cancel-Lock secrets
These secrets are used for the Cancel-Lock authentication system described in RFC 8315. This mechanism permits verifying that the withdrawal of an article is valid, that is to say the poster, posting agent, moderator, or injecting agent that processed the original article has requested to withdraw it via the use of a cancel control article or a Supersedes header field.

You'll need to build INN with version 3.3.0 or later of libcanlock to embed Cancel-Lock support. This library is available at <https://micha.freeshell.org/libcanlock/>. The "configure" script will automatically enable Cancel-Lock support if it finds libcanlock; you may have to specify the --with-canlock option to help "configure" find it.

The "cancels" group is defined as follows (you should naturally use other passwords than the following ones):

```
    cancels {
        canlockadmin: [ "9kc3ZtAACpNZRGtmYiPlbfkDacqNwPbcEfzFodc5X48g" ]
        canlockuser:  [ "TSrg41qEbp6AyZuQoIIHo6sUzFkBLOocJYN3KsUVdgft" ]
    }
```

If one of the canlockadmin or canlockuser parameters is not an empty list, nnrpd will add information to every posted article that will permit other news servers to later ensure that an attempt to cancel or supersede the article is not forged, and really originates from the authenticated original sender or the administrator of the local server.

If your users are not individually authenticated or identifiable with a unique static IP, you must not set canlockuser as otherwise anyone would be able to cancel the articles of any other person with the same assigned identity. If all or only some of your users are individually authenticated or identifiable, you can set canlockuser and make sure to parameterize addcanlockuser to "none" in all the access groups in readers.conf that are shared between several different persons with the same identity.

More concretely, for each secret in canlockadmin, nnrpd adds two Base64-encoded hashes to a Cancel-Lock header field. These hashes are based on the secret and the Message-ID of the article. If this field already exists, it will just append the Base64-encoded hashes to its end. One hash uses the SHA-1 algorithm (for interoperability reasons as not all news software implement SHA-256), and the other hash uses the mandatory SHA-256 algorithm per RFC 8315. Besides, nnrpd will similarly add two Base64-encoded hashes for each secret in canlockuser; these hashes are based on the secret, the identity assigned in readers.conf to the connection or its static IP (depending on the setting of addcanlockuser), and the Message-ID of the article.

When a cancel or supersede article is posted by an authenticated user, nnrpd will add to a Cancel-Key header field two pre-images for each secret in canlockuser. (This is why it is important, if you have set canlockuser, to parameterize addcanlockuser to "none" in all the access groups in readers.conf not corresponding to individual persons.) Other news servers can then hash one of these pre-images with SHA-1 or SHA-256 algorithms (one is enough) and verify that the resulted Base64-encoded hash is the same as the one present in the Cancel-Lock header field of the original article. (Necessarily, the same authenticated user on the same local server sent the original article.) When receiving articles with a Cancel-Key header field (locally or from other peers), innd applies that check to verify the authenticity of the withdrawal before deciding to honour it.

Naturally, no pre-images for each secret in canlockadmin are added by nnrpd. As these pre-images are not based on a user name, only the news administrator can generate them (with the gencancel tool shipped with INN) and then inject the cancel or supersede request with for instance inews. The news administrator is therefore capable to send authenticated withdrawal requests for articles posted by all the users of his news server, be they authenticated or not.

After this (little) introduction to explain what Cancel-Lock is for, here are the two relevant parameters:

canlockadmin

This parameter expects a list of strings. It is unset by default (no admin hashes will be generated). If this parameter is not an empty list, each provided secret will be used to generate admin hashes.

To maximize security, secrets should have a length of at least the output size of the hash function used (32 octets for SHA-256). You can for instance generate a strong secret based on 33 random octets (so that the last character is not systematically "=", as it happens when Base64-encoding 32 random octets) with:

```
    % openssl rand -base64 33
    nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8

```

and use it as follows:

```
    canlockadmin: [ "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ]

```

The purpose of providing several secrets is when you want to rotate secrets. For instance, if your policy is to change secrets each year, you can use two secrets during a transition period:

```
    canlockadmin: [ "rH5L8geEzkNVvpAZQMJJcd4AYkpSkkx5S/4qewPDA/U="
                    "nfwx6FS+U/dXXXqTOTp1Z5J9glV9UpjyhUcVcsDqXSC8" ]

```

Withdrawals of previously posted articles will still work with the old secret (still added to the Cancel-Key header field).

As all posted articles will have a Cancel-Lock header field with the admin secret, you should also set canlockuser (and individually authenticate the posters) because otherwise posters may not be able to withdraw their own articles (unless their posting agents generate Cancel-Lock header fields themselves with their own secrets).

canlockuser

This parameter expects a list of strings. It is unset by default (no user-specific hashes will be generated). The same recommendation of more than 32 random octets applies, and the secrets must not be the same as canlockadmin.

If this parameter is not an empty list, each provided secret will be used to generate hashes based on the identity assigned to users by readers.conf or their static IP (depending on the setting of addcanlockuser). Beware that if your users are not individually authenticated, you must not set canlockuser as otherwise anyone would be able to cancel the articles of any other person with the same assigned identity. If needed, you can deactivate the generation of user-specific hashes in access groups shared between several different persons with the same identity in readers.conf by setting addcanlockuser to "none" in these access groups (it may for instance be the case for localhost connections, if some articles are injected with inews from an external source).

When using canlockuser, you should also set canlockadmin because you may otherwise not always be able to generate the needed hash to cancel an article posted by the users of your news server (notably if you do not manage to find out the identity a user had when posting the original article).

## HISTORY
Documentation written by Julien Elie for InterNetNews.

## SEE ALSO
gencancel(1), nnrpd(8), readers.conf(5).