actsync

package: inn

title: actsync(8)

summary: Synchronize newsgroups

text:
# actsync(8)

## NAME
actsync, actsyncd - Synchronize newsgroups

## SYNOPSIS
actsync [-AkmT] [-b hostid] [-d hostid] [-g max] [-i ignore-file] [-I hostid] [-l hostid] [-n name] [-o format] [-p min-unchanged] [-q hostid] [-s size] [-t hostid] [-v verbosity] [-w seconds] [-z seconds] [host] host

actsyncd config [debug-level [debug-format]]

## IN A NUTSHELL
These programs permit keeping the list of newsgroups your news server carry synchronized with an external source.

For instance, you can decide to carry the same newsgroups as another news server or as the ones listed in a file from an external FTP site, and therefore synchronizing with the chosen source on a daily basis by running actsyncd in a cron job.

If you only want a subset of newsgroups from that source, it can be parameterized in the actsync.ign configuration file in the pathetc directory.

INN comes with a default configuration for fetching the list of newsgroups from "ftp.isc.org". You can read about the policies used for maintaining that active file at <https://ftp.isc.org/pub/usenet/CONFIG/README>. Just make sure actsync.cfg (the configuration file) and actsync.ign (the synchronization rules) suit your needs, and run:

```
    actsyncd <pathetc>/actsync.cfg
```

You'll find more detailed examples of use below in this man page.

## DESCRIPTION
actsync permits one to synchronize, compare, or merge two active files. With this utility one may add, change, or remove newsgroups on the local news server to make it similar to the list of the newsgroups found on another system or file. The synchronization need not be exact. Local differences in newsgroup lists may be maintained and preserved. Certain newsgroup errors may be detected and optionally corrected.

There are several reasons to run actsync (or actsyncd) on a periodic basis. Among the reasons are:

- A control message to add, change or remove a newsgroup may fail to reach your site.

- Your control.ctl may be out of date or incomplete.

- News articles for a new newsgroup may arrive ahead (sometimes days ahead) of the control message.

- Control messages may be forged, thus bypassing the restrictions found in control.ctl unless you set up PGP authentication (and even then, not all hierarchies use PGP authentication).

- Your active file may have been trashed.

If either host argument begins with "." or "/", it is assumed to be the name of a file containing information in the active(5) format. The getlist(1) utility may be used to obtain a copy of a remote system's active file via its NNTP server, or an FTP client program can retrieve such a file from an FTP archive (such as ftp.isc.org available in both FTP and HTTPS <https://ftp.isc.org/pub/usenet/CONFIG/active>; see more about this below). Newsgroup information from a file may be treated as if it was obtained from a host. In this man page, the host arguments on the command line are called hosts, even though they may be file names.

If a host argument does not begin with "." or "/", it is assumed to be a hostname or Internet address. In this case, actsync will attempt to use the NNTP protocol to obtain a copy of the specified system's active file. If the host argument contains ":", the right side will be considered the port to connect to on the remote system. If no port number is specified, actsync will connect to port 119.

Regardless how the active file information is obtained, the actions of actsync remain the same.

The first host specified is taken to be the local host, the one where any changes would be made. The second host specified is the remote host that is being synchronized with. If only one host is specified, it is assumed to be the remote host to synchronize with, and the local host is assumed to be the default local NNTP server as specified by the NNTPSERVER environment variable or by the server value found in inn.conf.

If either host is specified as "-", the default server will be used for that host, determined as described above.

The newsgroup synchronization, by default, involves all newsgroups found on both hosts. One may also synchronize a subset of newsgroups by directing actsync to ignore certain newsgroups from both systems. Only newsgroups with valid names will be synchronized. To be valid, a newsgroup name must consist only of alphanumeric characters, ".", "+", "-", and "_". One may not have two "." characters in a row. The first character must be alphanumeric, as must any character following ".". The name may not end in a "." character.

The actsyncd daemon provides a convenient interface to configure and run actsync. If a host is not initially reachable, the daemon will retry up to 9 additional times, waiting 6 minutes before each retry. This daemon runs in the foreground, sending output to standard output and standard error. It then uses mod-active(8) to update the active file if there are commands for ctlinnd in its output.

The configuration filename for the daemon is given as a command line argument, usually actsync.cfg in pathetc. The config file can contain the following options:

```
    host=<host>
    ftppath=<path-to-active>
    ignore_file=<ignore-file>
    flags=<actsync-options>
```

The "host=", "ignore_file=", and "flags=" lines are mandatory. Each keyword must start at the beginning of the line, and there may be no whitespace before the "=" character. Blank lines are ignored, as are comment lines that start with "#". Any other lines may produce undefined results.

The <host> setting refers to the second (remote) host parameter to actsync. If <path-to-active> is provided, <host> is accessed as an FTP server, retrieving the file named. If the filename ends in ".gz" or ".Z", it will be automatically uncompressed after retrieval. <ignore-file> names the ignore file used by actsync (the -i option). <actsync-options> contains any other flags that you wish to pass to actsync.

Note that one should not include -i or -o options in the "flags=" line; they are automatically taken care of by actsyncd.

One may produce a trial actsyncd run without changing anything on the server by supplying the debug-level argument:

```
    actsyncd <pathetc>/actsync.cfg 2
```

The debug-level causes actsyncd to run actsync with a -v debug-level flag (overriding any -v flag on the "flags=" line), not make any changes to the active file, write a new active file to standard output, and write debug messages to standard error. Note that using debug-level is only supported when synchronizing with another news server, not with FTP.

If the debug-format argument is also given to actsyncd, the data written to standard output will be in -o debug-format instead of in "-o a1" format.

INN comes with default values of "ftp.isc.org" for <host> and "/pub/usenet/CONFIG/active.gz" for <path-to-active>. You can read about the policies used for maintaining that active file at <https://ftp.isc.org/pub/usenet/CONFIG/README>. Consider synchronizing from this file on a daily basis by using a cron job.

## OPTIONS
actsync takes the following options.

In all of the following options, the hostid parameter takes one of the following values:

```
    0    neither server
    1    local default server
    2    remote server
    12   both servers
    21   both servers
```

In other words, 1 refers to the local host (the first host argument on the actsync command line) and 2 refers to the remote host (the second host argument, or the only one if only one is given).

-A

actsync tries to authenticate using the username and password information in passwd.nntp(5) before issuing the LIST command.

-b hostid

This flag causes actsync to ignore for synchronization purposes newsgroups with "bork.bork.bork"-style names (newsgroups whose last 3 components are identical). For example, the following newsgroups have bork-style names:

```
    alt.helms.dork.dork.dork
    alt.auto.accident.sue.sue.sue
    alt.election.vote.vote.vote

```

The default is "-b 0"; no newsgroups are ignored because of bork-style names.

-d hostid

This flag causes actsync to ignore newsgroups that have all numeric path components. For example, the following newsgroups have numeric path components:

```
    alt.prime.chongo.23209
    391581.times.2.to_the.216193.power.-1
    99.bottles.of.treacle.on.the.wall
    linfield.class.envio_bio.101.d

```

The newsgroups directory of a newsgroup with a all numeric component could conflict with an article from another group if stored using the tradspool storage method; see storage.conf(5). For example, the directory for the first newsgroup listed above is the same path as article number 23209 from the newsgroup:

```
    alt.prime.chongo

```

The default is "-d 0"; all numeric newsgroups from both hosts will be processed.

-g max

Ignore any newsgroup with more than max levels. For example, "-g 6" would ignore:

```
    alt.feinstien.votes.to.trash.freedom.of.speech
    alt.senator.exon.enemy.of.the.internet
    alt.crypto.export.laws.dumb.dumb.dumb

```

but would not ignore:

```
    alt.feinstien.acts.like.a.republican
    alt.exon.amendment
    alt.crypto.export.laws

```

If max is 0, then the max level feature is disabled.

By default, the max level feature is disabled.

-i ignore-file

The ignore-file, usually actsync.ign in pathetc, allows one to have a fine degree of control over which newsgroups are ignored. It contains a set of rules that specifies which newsgroups will be checked and which will be ignored. By default, these rules apply to both hosts. This can be modified by using the -I flag.

Blank lines and text after a "#" are considered comments and are ignored.

Rule lines consist of tokens separated by whitespace. Rule lines may be one of two forms:

```
    c <newsgroup> [<type> ...]
    i <newsgroup> [<type> ...]

```

If the rule begins with a "c", the rule requests certain newsgroups to be checked. If the rule begins with an "i", the rule requests certain newsgroups to be ignored. The <newsgroup> field may be a specific newsgroup, or a uwildmat pattern.

If one or more <type>s are specified, then the rule applies to the newsgroup only if it is of the specified type. Types refer to the 4th field of the active file; that is, a type may be one of:

```
    y
    n
    m
    j
    x
    =group.name

```

Unlike active files, the "group.name" in an alias type may be a newsgroup name or a uwildmat pattern. Also, "=" is equivalent to "=*".

On each rule line, no pattern type may be repeated. For example, one may not have more than one type that begins with "=", per line. However, one may achieve an effect equivalent to using multiple "=" types by using multiple rule lines affecting the same newsgroup.

By default, all newsgroups are candidates to be checked. If no ignore-file is specified, or if the ignore file contains no rule lines, all newsgroups will be checked. If an ignore file is used, each newsgroup in turn is checked against the ignore file. If multiple lines match a given newsgroup, the last line in the ignore file is used.

For example, consider the following ignore file lines:

```
    i *.general
    c *.general m
    i nsa.general

```

The newsgroups ba.general and mod.general would be synchronized if moderated and ignored if not moderated. The newsgroup nsa.general would be ignored regardless of moderation status. All newsgroups not matching *.general would be synchronized by default.

-I hostid

This flag restricts which hosts are affected by the ignore file. This flag may be useful in conjunction with the -m flag. For example:

```
    actsync -i actsync.ign -I 2 -m host1 host2

```

will keep all newsgroups currently on host1. It will also only compare host1 groups with non-ignored newsgroups from host2.

The default is "-I 12"; newsgroups from both hosts are ignored per the file specified with -i.

-k

By default, any newsgroup on the local host that has an invalid name will be considered for removal. This causes actsync simply ignore such newsgroups. This flag, used in combination with -m, will prevent any newsgroup from being scheduled for removal.

-l hostid

This flag causes problem newsgroups of type "=" to be considered as errors. Newsgroups of type "=" are newsgroups active entries that have a fourth field that begins with "="; i.e., newsgroups that are aliased to other newsgroups. A problem newsgroup is one for which one of the following is true:

- Aliased to itself.

- In an alias chain that loops around to itself.

- In an alias chain longer than 16 groups.

- Aliased to a non-existent newsgroup.

- Aliased to a newsgroup that has an error of some kind.

However, a newsgroup that is equivalent to an ignored newsgroup is not a problem.

The default is "-l 12": problem newsgroups from both hosts are marked as errors.

-m

Merge newsgroups instead of sync. By default, if a newsgroup exists on the local host but not the remote, it will be scheduled to be removed. This flag disables this process, permitting newsgroups unique to the local host to be kept.

-n name

Depending on -o, the ctlinnd(8) command may be used to create newsgroups as necessary. When this is done, the default creator name used is "actsync". This flag changes the creator name to name.

-o format

Determine the output or action format of this utility. format may be one of:

a

Output in active(5) format.

a1

Output in active(5) format and output non-error ignored groups from the local host.

ak

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for any newsgroup being created.

aK

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for all newsgroups found on that host.

a1k

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for any newsgroup being created and output non-error ignored groups from the local host.

a1K

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for all newsgroups found on that host and output non-error ignored groups from the local host.

ak1

Same as "a1k".

aK1

Same as "a1K".

c

Output as commands to ctlinnd.

x

No output. Instead, directly run ctlinnd commands.

xi

No output. Instead, directly run ctlinnd commands in an interactive mode.

The "a", "a1", "ak", "aK", "a1k", "a1K", "ak1", and "aK1" style formats allow one to format new active file instead of producing ctlinnd commands. They use high and low values of 0000000000 and 0000000001 respectively for newsgroups that are created unless otherwise specified. The "ak" and "aK" variants change the high and low values (2nd and 3rd active fields). In the case of "ak", newsgroups created take their high and low values from the remote host. In the case of "aK", all newsgroups found on the remote host take their high and low values from it.

The "c" format produces ctlinnd commands. No actions are taken because actsync simply prints ctlinnd commands on standard output. This output format is useful to let you see how the local host will be affected by the sync (or merge) with the remote host.

The sync (or merge) may be accomplished directly by use of the "x" or "xi" format. With this format, actsync uses the execl(2) system call to directly execute ctlinnd commands. The output of such exec calls may be seen if the verbosity level is at least 2.

The actsync utility will pause for 4 seconds before each command is executed if "-o x" is selected. See the -z flag below for discussion of this delay and how to customize it.

The "xi" format interactively prompts on standard output and reads directives on standard input. One may pick and choose changes using this format.

Care should be taken when producing active(5) formatted output. One should check to be sure that actsync exited with a zero status prior to using such output. Also one should realize that such output will not contain lines ignored due to -i even if "-p 100" is used.

By default, "-o c" is assumed.

-p min-unchanged

By default, the actsync utility has safeguards against performing massive changes. If fewer than min-unchanged percent of the non-ignored lines from the local host remain unchanged, no actions (output, execution, etc.) are performed and actsync exits with a non-zero exit status. The min-unchanged value may be a floating point value such as 66.667. A change is a local newsgroup line that was removed, added, changed, or found to be in error. Changing the 2nd or 3rd active fields via "-o ak" or "-o aK" are not considered changes by -p.

To force actsync to accept any amount of change, use the "-p 0" option. To force actsync to reject any changes, use the "-p 100" option.

Care should be taken when producing active(5) formatted output. One should check to be sure that actsync exited with a zero status prior to using such output. Also one should realize that such output will not contain lines ignored due to -i even if "-p 100" is used.

By default, 96% of the lines not ignored in the first host argument on the actsync command line must be unchanged. That is, by default, "-p 96" is assumed.

-q hostid

By default, all newsgroup errors are reported on standard error. This flag quiets errors from the specified hostid.

-s size

If size is greater than 0, then ignore newsgroups with names longer than size and ignore newsgroups aliased (by following "=" chains) to names longer than size. Length checking is performed on both the local and remote hosts. By default, size is 0 and thus no length checking is performed.

-t hostid

Ignore improper newsgroups consisting of only a top component from the specified hostid. The following newsgroups are considered proper newsgroups despite top only names and therefore are exempt from this flag:

```
    control
    general
    junk
    test
    to

```

For example, the following newsgroup names are improper because they only contain a top level component:

```
    dole_for_pres
    dos
    microsoft
    windows95

```

The default is "-t 2"; that is, all improper top-level-only newsgroups from the remote host are ignored.

-T

This flag causes newsgroups on the remote host in new hierarchies to be ignored. Normally a newsgroup which only exists on the remote host, chongo.was.here for example, is created on the local host. However, if this flag is given and the local host does not have any other newsgroups in the same hierarchy (chongo.* in this case), the newsgroup in question will be ignored and will not be created on the local host.

-v verbosity

By default, actsync is not verbose. This flag controls the verbosity level as follows:

0

No debug or status reports (default).

1

Print summary, but only if work was needed or done.

2

Print actions, exec output, and summary, but only if work was needed or done.

3

Print actions, exec output, and summary.

4

Full debug output.

-w seconds

If "-o x" or "-o xi" is selected, ctlinnd will wait seconds seconds before timing out. The default value is "-w 30".

-z seconds

If "-o x" is selected, actsync will pause for seconds seconds before each command is executed. This helps prevent innd from being busied-out if a large number of ctlinnd commands are needed. One can entirely disable this sleeping by using "-z 0". By default, actsync will pause for 4 seconds before each command is executed if "-o x" is selected.

## EXAMPLES
Determine the difference (but don't change anything) between your newsgroup set and the one of another news server:

```
    actsync news.server.com
```

Same as above, with full debug and progress reports:

```
    actsync -v 4 news.server.com
```

Force a site to have the same newsgroups as some other site:

```
    actsync -o x master
```

This may be useful to sync a slave site to its master, or to sync internal site to a gateway.

Compare your site with news.server.com, disregarding local groups and certain local differences with it. Produce a report if any differences were encountered:

```
    actsync -v 2 -i actsync.ign news.server.com
```

where actsync.ign contains:

```
    # Don't compare to.* groups as they will differ.
    #
    i       to.*
    # These are our local groups that nobody else
    # (should) carry.  So ignore them for the sake
    # of the compare.
    #
    i       nsa.*
    # These groups are local favorites, so keep them
    # even if news.server.com does not carry them.
    #
    i       ca.dump.bob.dorman
    i       ca.keep.bob.dorman
    i       alt.tv.dinosaurs.barney.die.die.die
    i       alt.tv.dinosaurs.barney.love.love.love
    i       alt.sounds.*    =alt.binaries.sounds.*
```

To interactively sync against news.server.com, using the same ignore file:

```
    actsync -o xi -v 2 -i actsync.ign news.server.com
```

Based on newsgroups that you decided to keep, one could make changes to the actsync.ign file:

```
    # Don't compare to.* groups as they will differ.
    #
    i       to.*
    # These are our local groups that nobody else
    # (should) carry.  So ignore them for the sake
    # of the compare.
    #
    i       nsa.*
    # These groups are local favorites, so keep them
    # even if news.server.com does not carry them.
    #
    i       ca.dump.bob.dorman
    i       alt.tv.dinosaurs.barney.die.die.die
    i       alt.sounds.*    =alt.binaries.sounds.*
    # Don't sync test groups, except for ones that are
    # moderated or that are under the gnu hierarchy.
    #
    i       *.test
    c       *.test m        # check moderated test groups
    c       gnu.*.test
    c       gnu.test        # just in case it ever exists
```

Automatic processing may be set up by using the following actsync.cfg file:

```
    # Host to sync off of (host2).
    host=news.server.com
    # Location of the ignore file.
    ignore_file=<pathetc in inn.conf>/actsync.ign
    # Where news articles are kept.
    spool=<patharticles in inn.conf>
    # actsync(8) flags
    #
    # Automatic execs, report if something was done,
    # otherwise don't say anything, don't report
    # news.server.com active file problems, just ignore
    # the affected entries.
    flags=-o x -v 2 -q 2
```

and then by running actsyncd with the path to the config file:

```
    actsyncd <pathetc>/actsync.cfg
```

The command

```
    actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log
```

will operate in debug mode, not change the active file, write ctlinnd style commands to cmd.log, and write debug statements to dbg.log. (Note that using debug-level is only supported when synchronizing with another news server, not with FTP.)

To check only the major hierarchies against news.server.com, use the following actsync.ign file:

```
    # By default, ignore everything.
    #
    i       *
    # Check the major groups.
    #
    c       alt.*
    c       comp.*
    c       gnu.*
    c       humanities.*
    c       misc.*
    c       news.*
    c       rec.*
    c       sci.*
    c       soc.*
    c       talk.*
```

and the command:

```
    actsync -i actsync.ign news.server.com
```

To determine the differences between your old active and your current default server:

```
    actsync <pathetc>/active.old -
```

To report but not fix any newsgroup problems with the current active file:

```
    actsync - -
```

To detect any newsgroup errors on your local server, and to remove any *.bork.bork.bork-style silly newsgroup names:

```
    actsync -b 2 - -
```

The active file produced by:

```
    actsync <flags> -o x erehwon.honey.edu
```

is effectively the same as the active file produced by:

```
    cd <pathdb>
    ctlinnd pause 'running actsync'
    rm -f active.new
    actsync <flags> -o a1 erehwon.honey.edu > active.new
    rm -f active.old
    ln active active.old
    mv active.new active
    ctlinnd reload active 'running actsync'
    ctlinnd go 'running actsync'
```

It should be noted that the final method above, pausing the server and simply replacing the active file, may be faster if you are making lots of changes.

## FILES
pathbin/actsync

The C program itself used to synchronize, compare, or merge two active files.

pathbin/actsyncd

The Shell daemon which provides a convenient interface to configure and run actsync.

pathetc/actsync.cfg

The configuration file which specifies the settings to use.

pathetc/actsync.ign

The ignore file which contains a set of synchronization rules that specifies which newsgroups will be checked and which will be ignored.

## CAUTION
Careless use of this tool may result in the unintended addition, change, or removal of newsgroups. You should avoid using the "x" output format until you are sure it will do what you want.

## BUGS
If a newsgroup appears multiple times, actsync will treat all copies as errors. However, if the group is marked for removal, only one rmgroup will be issued.

## HISTORY
Written by Landon Curt Noll <chongo@toad.com> for InterNetNews. Updated to support FTP fetching by David Lawrence <tale@isc.org>. Converted to POD by Russ Allbery <eagle@eyrie.org>.

By Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).

Copyright (c) Landon Curt Noll, 1993. All rights reserved.

Permission to use and modify is hereby granted so long as this notice remains. Use at your own risk. No warranty is implied.

## SEE ALSO
active(5), ctlinnd(8), getlist(1), inn.conf(5), libinn_uwildmat(3), mod-active(8), passwd.nntp(5), simpleftp(1).


archive

title: archive(8)

summary: Usenet article archiver

text:
# archive(8)

## NAME
archive - Usenet article archiver

## SYNOPSIS
archive [-cfr] [-a archive] [-i index] [-p pattern] [input]

## DESCRIPTION
archive makes copies of files specified on its standard input. It is normally run either as a channel feed under innd or by a script before news.daily is run.

archive reads the named input file, or standard input if no file is given. The input is taken as a sequence of lines; blank lines and lines starting with a number sign ("#") are ignored. All other lines should specify the token of an article to archive. Every article is retrieved from a token, and the Xref header field is used to determine the target file in the archive directory. You can limit the targets taken from the Xref header field with the -p option.

Files are copied to a directory within the archive directory, patharchive in inn.conf (or some other directory given with -a). The default is to create a hierarchy that mimics a traditional news spool storage of the given articles; intermediate directories will be created as needed. For example, if the input token represents article 2211 in the newsgroup comp.sources.unix, archive will by default store the article as:

```
    comp/sources/unix/2211
```

in the archive area. This can be modified with the -c and -f options.

## OPTIONS
-a archive

If the -a flag is given, its argument specifies the root of the archive area, instead of patharchive in inn.conf.

-c

If the -c flag is given, directory names will be flattened as described under the -f option. Then, additionally, all posts will be concatenated into a single file, appending to that file if it already exists. The file name will be "YYYYMM", formed from the current time when archive is run. In other words, if given an article in comp.sources.unix on December 14th, 1998, the article would be appended to the file:

```
    comp.sources.unix/199812

```

in the archive area.

Articles will be separated by a line containing only "-----------".

-f

If the -f flag is used, directory names will be flattened, replacing the slashes with the periods. In other words, article 2211 in comp.sources.unix will be written to:

```
    comp.sources.unix/2211

```

in the archive area.

-i index

If the -i flag is used, archive will append one line to the file index for each article that it archives. This line will contain the destination file name, the Message-ID header field, and the Subject header field of the message, separated by spaces. If either header is missing (normally not possible if the article was accepted by innd), it will be replaced by "<none>". The headers will be transformed using the same rules as are used to generate overview data (unfolded and then with tabs, CR, and LF replaced by spaces).

-p pattern

Limits the targets taken from the Xref header field to the groups specified in pattern. pattern is a uwildmat pattern matching newsgroups that you wish to have archive handle.

-r

By default, archive sets its standard error to pathlog/errlog. To suppress this redirection, use the -r flag.

## RETURN VALUE
If the input is exhausted, archive will exit with a zero status. If an I/O error occurs, it will try to spool its input, copying it to a file. If there was no input filename, the standard input will be copied to pathoutgoing/archive and the program will exit. If an input filename was given, a temporary file named input.bch (if input is an absolute pathname) or pathoutgoing/input.bch (if the filename does not begin with a slash) is created. Once the input is copied, archive will try to rename this temporary file to be the name of the input file, and then exit.

## EXAMPLES
A typical newsfeeds(5) entry to archive most source newsgroups is as follows:

```
    source-archive!\
        :!*,*sources*,!*wanted*,!*.d\
        :Tc,Wn\
        :<pathbin>/archive -f -i <patharchive>/INDEX
```

Replace <pathbin> and <patharchive> with the appropriate paths.

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

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

branch: sisyphus


title: auth_krb5(8)

summary: nnrpd Kerberos v5 authenticator

text:
# auth_krb5(8)

## NAME
auth_krb5 - nnrpd Kerberos v5 authenticator

## SYNOPSIS
auth_krb5 [-i instance]

## DESCRIPTION
This program does authentication for nnrpd against a Kerberos v5 KDC. This is NOT real Kerberos authentication using service tickets; instead, a username and password is used to attempt to obtain a Kerberos v5 TGT to confirm that they are valid. As such, this authenticator assumes that nnrpd has been given the user's username and password, and therefore is not as secure as real Kerberos authentication. It generally should only be used with NNTP over TLS to protect the password from sniffing.

Normally, you do not want to use this authenticator. Instead, use ckpasswd with PAM support and configure the nnrpd PAM stack to use a Kerberos PAM module. A full Kerberos PAM module is more sophisticated about how it validates passwords and has a much broader array of options than this authenticator.

## OPTIONS
-i instance

If this option is given, instance will be used as the instance of the principal received from nnrpd and authentication will be done against that principal instead of the base principal. In other words, a principal like "user", when passed to auth_krb5 invoked with "-i nntp", will be transformed into "user/nntp" before attempting Kerberos authentication. Since giving one's password to nnrpd is not as secure as normal Kerberos authentication, this option supports a configuration where all users are given a separate instance just for news authentication with its own password, so their regular account password isn't exposed via NNTP.

## EXAMPLE
The following readers.conf(5) fragment tells nnrpd to authenticate users by attempting to obtain Kerberos v5 TGTs for them, appending an instance of "nntp" to usernames before doing so:

```
    auth kerberos {
        auth: "auth_krb5 -i nntp"
    }
    access kerberos {
        users: "*/nntp"
        newsgroups: example.*
    }
```

Access is granted to the example.* groups for all users who successfully authenticate.

## BUGS
Currently, any username containing realm information (containing "@") is rejected. This is to prevent someone from passing in a username corresponding to a principal in another realm that they have access to and gaining access to the news server via it. However, this is also something that people may wish to do under some circumstances, so there should be a better way of handling it (such as, perhaps, a list of acceptable realms or a -r flag specifying the realm in which to attempt authentication).

It's not clear the right thing to do when the username passed in contains a "/" and -i was also given. Right now, auth_krb5 will create a malformed Kerberos principal with multiple instances and attempt to authenticate against it, which will fail but perhaps not with the best error message.

## HISTORY
Originally written by Christopher P. Lindsey. This documentation was written by Russ Allbery <eagle@eyrie.org> based on Christopher's original README file.

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


batcher

title: batcher(8)

summary: Article batching for InterNetNews

text:
# batcher(8)

## NAME
batcher - Article batching for InterNetNews

## SYNOPSIS
batcher [-rv] [-a articles] [-A total-articles] [-b size] [-B total-size] [-i string] [-N batches] [-p process] [-s separator] host [input]

## DESCRIPTION
batcher reads a list of files and prepares news batches for the specified host. It is generally used to prepare UUCP feeds, but the resulting batches can be used by any application that uses rnews(1) to inject the articles. It is normally invoked by a script run out of cron that uses shlock to lock the host, followed by ctlinnd to flush the batch file. See send-uucp(8) for a front-end for batcher.

batcher reads the file input, or standard input if no file is given. If input is a relative file name, it is assumed to be in pathoutgoing as set in inn.conf. Blank lines and lines starting with a number sign ("#") are ignored. All other lines in the input should consist of one or two fields separated by a single space. The first field is the storage API token of an article. The second field, if present, specifies the size of the article in bytes.

By default, batches are written to standard output (which isn't very useful if more than one batch is output), but see the -p option.

## OPTIONS
-a articles

This flag limits the number of articles included in each batch. The default is no limit. A new batch will be started when either the total bytes or the number of articles written exceeds the specified limits.

-A total-articles

Limits the total number of articles written for all batches. As soon as the total number of articles written to batches reaches or exceeds total-articles, all additional articles in the input will be deferred. The default is no limit.

-b size

This flag sets the size limit for each batch; as soon as at least this much data has been written out, a new batch will be started. The default size is 60 KB. Using "-b 0" will allow unlimited batch sizes.

-B total-size

Limits the total number of bytes written for all batches. As soon as the total bytes written to batches reaches or exceeds total-size, all additional articles in the input will be deferred. The default is no limit.

-i string

A batch starts with an identifying line to specify the unpacking method to be used on the receiving end. When this flag is used, string, followed by a newline, will be output at the start of each batch. The default is to have no initial string (under the assumption that either the processor specified with the -p flag or some other later process will add the appropriate line).

-N batches

Limits the total number of batches written. As soon as the number of batches written reaches or exceeds batches, all additional articles in the input will be deferred. The default is no limit.

-p process

By default, batches are written to standard output, which is not useful when more than one output batch is created. If this option is given, each batch will instead be fed via a pipe to the shell command process. The process argument must be an sprintf(3) format string, which may have a single %s parameter that will be replaced with the host name. A common value is:

```
    ( echo '#! gunbatch' ; exec gzip -c ) | uux - -r -z %s!rnews

```

which generates gzip-compressed batches and feeds them to uux.

-r

By default, batcher reports errors to pathlog/errlog. To suppress this redirection and report errors to standard error, use the -r flag.

-s separator

Each article in a batch starts with a separator line that indicates the size of the article. separator must be an sprintf(3) string, which may have a single %ld in the string that will be replaced with the size of the article. If the separator is not empty, a newline will also be appended to it when it is added to the beginning of each article. The default separator is:

```
    #! rnews %ld

```

and this should rarely be changed.

-v

Upon exit, batcher reports statistics via syslog. With this flag, the statistics will also be printed to standard output.

## EXIT STATUS
If the input is exhausted and all batches are created successfully, batcher will exit with a zero status.

If any of the limits specified with -A, -B, or -N flags are reached, or if there is an error in writing a batch, batcher will try to spool the remaining input by copying it to a file as follows:

- If there was no input filename, the remaining input will be copied to pathoutgoing/host.

- If an input filename was given, the remaining input will be copied to a temporary file named by appending ".bch" to the end of input (and qualified by adding pathoutgoing if input was not a fully qualified path). If this happens successfully, batcher will then try to rename this temporary file to input (thus replacing input with a copy of itself with all of lines for the successfully batched articles removed).

Upon receipt of an interrupt or termination signal, batcher will finish batching the current article, close the batch, and then rewrite the batch file as described above.

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

## SEE ALSO
ctlinnd(8), inn.conf(5), newsfeeds(5), rnews(1), send-uucp(8), shlock(1).


buffchan

title: buffchan(8)

summary: Buffered file\-writing backend for INN

text:
# buffchan(8)

## NAME
buffchan - Buffered file-writing backend for INN

## SYNOPSIS
buffchan [-bru] [-c lines] [-C seconds] [-d directory] [-f num-fields] [-l lines] [-L seconds] [-m map] [-p pid-file] [-s format]

## DESCRIPTION
buffchan reads lines from standard input and copies the initial fields in each line to the files named by the remaining fields on the line. buffchan is intended to be called by innd as an exploder feed.

The input is interpreted as a sequence of lines. Each line contains a fixed number of initial fields, followed by a variable number of filename fields. All fields in a line are separated by whitespace and do not contain any whitespace. The default number of initial fields is one.

For each line of input, buffchan writes the initial fields, separated by a space and followed by a newline, to each of the files named in the filename fields. The output files are kept open and are only flushed or closed based on the schedule given by the -c, -C, -l, and -L options.

As an exploder feed (see newsfeeds(5) for an explanation), buffchan interprets lines beginning with an exclamation point as commands. Besides "!begin" (which only marks the start of the feed), there are three supported commands:

!flush [site]

The flush command closes and reopens all open files. An optional site can be specified, in which case buffchan flushes only that file. This command is analogous to the "ctlinnd flush" command. This command can be sent via innd using "ctlinnd send buffchan-site 'flush site'". Applications can tell that flush has completed by renaming the file before issuing the command. When the original file name has reappeared, the flush is complete. If fchmod(3) is available, buffchan also changes the file to read-only while it's actively writing to it and changes it back to read/write once it has been closed. It will change the mode back to read-only only if it reopens the same file.

!drop [site]

The drop command is similar to the flush command, except that no files are reopened. If given an argument, only the specified site is dropped; otherwise, all sites are dropped. (Note that a site will be restarted if the input stream mentions the site again.) When a "ctlinnd drop site" command is sent, innd will automatically forward the command to buffchan if the site is listed as a funnel feeding into the buffchan exploder. To drop all sites, use "ctlinnd send buffchan-site drop".

!readmap

The map file specified with the -m option, if given, will be reloaded.

Once buffchan opens a file, it keeps it open (in the absence of a drop command). The input must therefore never specify more files than the maximum number of files a process may open.

## OPTIONS
-b

Force the output to be buffered. (This is generally the default, but it may depend on the operating system.) If -b is given, a buffer size of BUFSIZ (a constant of the system standard I/O library) is used.

-c lines

If the -c flag is given, buffchan will close and reopen a file after every lines lines are written to the file.

-C seconds

If the -C flag is given, buffchan will close and reopen a file if it has been open for more than seconds seconds.

-d directory

By default, buffchan writes its output into the pathoutgoing directory. This flag may be used to specify a directory the program should change to before starting. If this flag is used, the default for the -s flag (see below) is changed to be a simple %s (in other words, output files are considered to be relative to directory).

-f num-fields

By default, each line is expected to contain one fixed field followed by some number of filename fields. If this flag is given, num-fields will be used as the number of initial fixed fields.

-l lines

If the -l flag is given, buffchan will flush the output after every lines lines are written to a file.

-L seconds

If the -L flag is given, buffchan will flush each output file every seconds seconds.

-m map

Map files translate the names in the filename fields on each line into filenames that should be used instead. It's used primarily when short names are used in newsfeeds, but the output files should use the full domain names of remote peers. In the map file, blank lines and lines starting with a number sign ("#") are ignored. All other lines should have two host names separated by a colon. The first field is the name that may appear in the input stream; the second field names the file to be used when the name in the first field appears.

For example, the following map file may be used to map the short names used in the example below to the full domain names:

```
    # This is a comment
    uunet:news.uu.net
    foo:foo.com
    munnari:munnari.oz.au

```

-p pid-file

If the -p option is given, buffchan will write a line containing its process ID (in text) to the specified file when it starts.

-r

By default, buffchan sends its error messages to pathlog/errlog. To suppress this redirection and send error messages to standard error, use the -r flag.

-s

The -s flag may be used to specify a format that maps a filename from the filename fields at the end of each line to an actual filename. This is a sprintf(3) format string that should contain a single instance of %s, which will be replaced with the value of the filename field (possibly after mapping with the map file from -m). The default value is pathoutgoing/%s.

-u

If the -u flag is used, the output will be unbuffered.

## EXAMPLES
If buffchan is invoked with "-f 2" and given the following input:

```
    news.software.nntp <1643@munnari.oz.au> foo uunet
    news.software.nntp <102060@litchi.foo.com> uunet munnari
    comp.sources.unix <999@news.foo.com> foo uunet munnari
```

then the file foo in pathoutgoing will have these lines:

```
    news.software.nntp <1643@munnari.oz.au>
    comp.sources.unix <999@news.foo.com>
```

the file munnari in pathoutgoing will have these lines:

```
    news.software.nntp <102060@litchi.foo.com>
    comp.sources.unix <999@news.foo.com>
```

and the file uunet in pathoutgoing will have these lines:

```
    news.software.nntp <1643@munnari.oz.au>
    news.software.nntp <102060@litchi.foo.com>
    comp.sources.unix <999@news.foo.com>
```

Using buffchan this way can be done in newsfeeds with for instance:

```
    foo:*,@misc.*:Ap,Tm:buffchan!
    munnari:*,@rec.*:Ap,Tm:buffchan!
    uunet:*:Ap,Tm:buffchan!
    buffchan!:*:Tx,WGm*:<pathbin>/buffchan -f 2
```

It will generate the examples above. See the "W" flag in newsfeeds(5) for how to parameterize the output.

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

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


ckpasswd

title: ckpasswd(8)

summary: nnrpd password authenticator

text:
# ckpasswd(8)

## NAME
ckpasswd - nnrpd password authenticator

## SYNOPSIS
ckpasswd [-gs] [-d database] [-f filename] [-u username -p password]

## DESCRIPTION
ckpasswd is the basic password authenticator for nnrpd, suitable for being run from an auth stanza in readers.conf. See readers.conf(5) for more information on how to configure an nnrpd authenticator.

ckpasswd accepts a username and password from nnrpd and tells nnrpd(8) whether that's the correct password for that username. By default, when given no arguments, it tries to check the password using PAM if support for PAM was found when INN was built. Failing that, it tries to check the password against the password field returned by getpwnam(3). Note that these days most systems no longer make real passwords available via getpwnam(3) (some still do if and only if the program calling getpwnam(3) is running as root).

When using PAM, ckpasswd identifies itself as "nnrpd", not as "ckpasswd", and the PAM configuration must be set up accordingly. The details of PAM configuration are different on different operating systems (and even different Linux distributions); see "EXAMPLES" below for help getting started, and look for a pam(7) or pam.conf(4) manual page on your system.

When using any method other than PAM, ckpasswd expects all passwords to be stored encrypted by the system crypt(3) function and calls crypt(3) on the supplied password before comparing it to the expected password. Any password hashing algorithm supported by your libc or libcrypt can be used.

## OPTIONS
-d database

Read passwords from a database (ndbm, gdbm or dbm format depending on what your system has) rather than by using getpwnam(3). ckpasswd expects database.dir and database.pag to exist and to be a database keyed by username with the encrypted passwords as the values. While INN doesn't come with a program intended specifically to create such databases, on most systems it's fairly easy to write a Perl script to do so. Something like:

```
    #!/usr/bin/perl
    use NDBM_File;
    use Fcntl;
    tie (%db, 'NDBM_File', '/path/to/database', O_RDWR|O_CREAT, 0640)
        or die "Cannot open /path/to/database: $!\n";
    $| = 1;
    print "Username: ";
    my $user = <STDIN>;
    chomp $user;
    print "Password: ";
    my $passwd = <STDIN>;
    chomp $passwd;
    my @alphabet = ('.', '/', 0..9, 'A'..'Z', 'a'..'z');
    my $salt = join '', @alphabet[rand 64, rand 64];
    $db{$user} = crypt ($passwd, $salt);
    untie %db;

```

Note that this will echo back the password when typed; there are obvious improvements that could be made to this, but it should be a reasonable start. Sometimes a program like this will be available with the name dbmpasswd.

This option will not be available on systems without ndbm, gdbm or dbm libraries.

-f filename

Read passwords from the given file rather than using getpwnam(3). Each line of the file should look something like:

```
    username:$5$Hlb2yXPd$2nOO/QR9P1mnRFr/i6L9ybxbgSDXd4UlatKqbcY4eoB
    joe:FCjOJnpOo50IE:Old weak hash algorithm used for Joe

```

Each line has at least two fields separated by a colon. The first field contains the username; the second field contains a password hashed with the crypt(3) function. Additional colons and data may appear after the encrypted password; that data will be ignored by ckpasswd. Lines starting with a number sign ("#") are ignored.

INN does not come with a utility to create the encrypted passwords, but OpenSSL can do so and it's also a quick job with Perl (see the one-line example script below).

A line in filename for the user "user" with the password "pass" would be "user:" followed with the output of the following command using SHA-256 as hashing scheme:

```
    % openssl passwd -5 pass
    $5$UIhtJSBOaC0Ap3Vk$nbKgmykshoQ2HmvA3s/nI.X4uhhNHBKTYhBS3pYLjJ6

```

See the openssl-passwd(1) man page for the list of hashing schemes it can generate. You must take one that your system crypt(3) function handles (type "man 3 crypt" or "man 5 crypt" to find the supported hashing schemes).

In case OpenSSL is not installed on your server, you can also use the following Perl command which does the same job with SHA-256 (see details below to set "YourSalt" to an appropriate value; 5 is the prefix for SHA-256, which does not expect any parameters):

```
    % perl -le 'print crypt("pass", q{$5$YourSalt$})'
    $5$YourSalt$V5hqwFg1nhKb5as6md9KTe5b2NyavsMS6dBYVKfp5W7

```

As Perl makes use of crypt(3), you have access to all available hashing schemes on your systems. For instance, if yescript is supported, you can generate an encrypted password with an argument like "$y$j9T$YourSalt$" to Perl crypt function, where "y" is the prefix for yescript, "j9T" the parameters passed to crypt_gensalt(3) to generate the hashed password (these parameters control the yescript configuration, and correspond in this example to the "YESCRYPT_DEFAULTS" flag, the recommended flavor which has "j" value in 2023, with cost factor of 4096 as block count and 32 as block size) and "YourSalt" a string which should be chosen at random and different for each user. The syntax and optimal length of the salt depend on the hashing scheme (e.g. a length multiple of 4 for yescript) and cryptographic recommendations (e.g. at least 32 random bits in length, following NIST SP 800-63B recommendations in 2023).

To put it in a nutshell, in the following command, you only have to change the password "pass" and the "YourSalt" random string, different for each user, and leave the rest of the command as-is:

```
    % perl -le 'print crypt("pass", q{$y$j9T$YourSalt$})'
    $y$j9T$YourSalt$X4tB48vKNDT6mK0vNOc7ppKPWvEsyMg5LwoQfO50r2A

```

A random salt of 12 characters can be obtained with the following command (the result corresponds to 72 random bits as each character is selected in a 6-bit range of 64 possible characters):

```
    % perl -le 'print join("",
          (".", "/", 0..9, A..Z, a..z)[map {rand 64} (1..12)])'
    k2W/17eJu58r

```

-g

Attempt to look up system group corresponding to username and return a string like "user@group" to be matched against in readers.conf. This option is incompatible with the -d and -f options.

-p password

Use password as the password for authentication rather than reading a password using the nnrpd authenticator protocol. This option is useful only for testing your authentication system (particularly since it involves putting a password on the command line), and does not work when ckpasswd is run by nnrpd. If this option is given, -u must also be given.

-s

Check passwords against the result of getspnam(3) instead of getpwnam(3). This function, on those systems that supports it, reads from /etc/shadow or similar more restricted files. If you want to check passwords supplied to nnrpd(8) against system account passwords, you will probably have to use this option on most systems. Most systems require special privileges to call getspnam(3), so in order to use this option you may need to make ckpasswd setgid to some group (like group "shadow") or even setuid root. ckpasswd has not been specifically audited for such uses! It is, however, a very small program that you should be able to check by hand for security.

This configuration is not recommended if it can be avoided, for serious security reasons. See "SECURITY CONSIDERATIONS" in readers.conf(5) for discussion.

-u username

Authenticate as username. This option is useful only for testing (so that you can test your authentication system easily) and does not work when ckpasswd is run by nnrpd. If this option is given, -p must also be given.

## EXAMPLES
See readers.conf(5) for examples of nnrpd(8) authentication configuration that uses ckpasswd to check passwords.

An example PAM configuration for /etc/pam.conf that tells ckpasswd to check usernames and passwords against system accounts is:

```
    nnrpd auth    required pam_unix.so
    nnrpd account required pam_unix.so
```

Your system may want you to instead create a file named nnrpd in /etc/pam.d with lines like:

```
    auth    required pam_unix.so
    account required pam_unix.so
```

This is only the simplest configuration. You may be able to include common shared files, and you may want to stack other modules, either to allow different authentication methods or to apply restrictions like lists of users who can't authenticate using ckpasswd. The best guide is the documentation for your system and the other PAM configurations you're already using.

To test to make sure that ckpasswd is working correctly, you can run it manually and then give it the username (prefixed with "ClientAuthname:") and password (prefixed with "ClientPassword:") on standard input. For example:

```
    (echo 'ClientAuthname: test' ; echo 'ClientPassword: testing') \
        | ckpasswd -f /path/to/passwd/file
```

will check a username of "test" and a password of "testing" against the username and passwords stored in /path/to/passwd/file. On success, ckpasswd will print "User:test" and exit with status 0. On failure, it will print some sort of error message and exit a non-zero status.

## HISTORY
Written by Russ Allbery <eagle@eyrie.org> for InterNetNews.

## SEE ALSO
crypt(3), nnrpd(8), pam(7), readers.conf(5).


cnfsheadconf

title: cnfsheadconf(8)

summary: Read and write CNFS headers

text:
# cnfsheadconf(8)

## NAME
cnfsheadconf - Read and write CNFS headers

## SYNOPSIS
cnfsheadconf [-hw] [-c class]

## DESCRIPTION
cnfsheadconf reads pathetc/cycbuff.conf and pathetc/storage.conf to determine which CNFS buffers are available. It then reads all of them or the specified cyclic buffer via the -c flag, and modifies the header as directed by the interactive user if -w is used.

## OPTIONS
-c class

Print the status of the specified class. It also modifies it in case -w is used.

-h

Print usage information and exit.

-w

Prompt for modifications to make to cycbuff header.

## HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. Converted to POD by Julien Elie.

## SEE ALSO
cycbuff.conf(5), inn.conf(5), storage.conf(5).


cnfsstat

title: cnfsstat(8)

summary: Show usage of CNFS buffers

text:
# cnfsstat(8)

## NAME
cnfsstat - Show usage of CNFS buffers

## SYNOPSIS
cnfsstat [-ahpPsv] [-c class] [-i seconds] [-l [seconds]] [-m buffer]

## DESCRIPTION
cnfsstat reads pathetc/cycbuff.conf and pathetc/storage.conf to determine which CNFS buffers are available. It then reads the specified cyclic buffers and shows their usage status. cnfsstat can be invoked from rc.news if docnfsstat is set to true in inn.conf, and the result is written to syslog(3).

## OPTIONS
-a

Besides its usual output, cnfsstat prints the age of the oldest article in the cycbuff. You may also want to use the -v flag to see extended consistency checks.

-c class

Only information for the specified class is printed.

-h

Print usage information and exit.

-i seconds

With this option, cnfsstat has an initial sleep of seconds seconds at startup. This is useful when cnfsstat is started at the same time as INN, so that it can wait a little before beginning performing its checks.

-l [seconds]

With this option, cnfsstat prints a status snapshot every seconds seconds, and only exits if an error occurs. When unspecified, the default interval is 600 seconds. At each iteration, cnfsstat checks whether the cycbuff.conf and storage.conf files have been modified, and loads the new configuration if needed.

-m buffer

Print information about the specified buffer in a format suitable for MRTG.

-p

Print an MRTG config file.

-P

Write PID into pathrun/cnfsstat.pid.

-s

Write output to syslog(3) instead of standard output.

-v

Write additional information, especially about consistency checks for article storage and the history file.

## HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. Converted to POD by Julien Elie.

## SEE ALSO
cycbuff.conf(5), history(5), inn.conf(5), rc.news(8), storage.conf(5).


controlchan

title: controlchan(8)

summary: Channel\-fed control message handler

text:
# controlchan(8)

## NAME
controlchan - Channel-fed control message handler

## SYNOPSIS
controlchan [-ch]

## DESCRIPTION
controlchan removes the responsibility for handling control messages (except cancels) from innd and instead processes them from a channel or file feed.

The two Perl modules "Encode" and "MIME::Parser" are required by controlchan.

To reduce load, controlchan keeps a copy of control.ctl and control.ctl.local in memory and checks permissions (including any required PGP headers) before any scripts are called. These two configuration files are automatically reloaded when controlchan notices they have been modified. Also, the default case of an unrecognized control article is handled internally. The "drop" case is handled with far less fuss.

Normally, controlchan is invoked by innd as configured in newsfeeds. An example entry is below. Make sure that the newsgroup "control.cancel" exists so that controlchan does not have to scan through cancels, which it will not be processing anyway.

```
    controlchan!\
        :!*,control,control.*,!control.cancel\
        :AC,Tc,Wnsm\
        :<pathbin in inn.conf>/controlchan
```

controlchan can also be manually invoked with a mere path to a file (containing a complete control article with its headers and its body) or a token on its standard input:

```
    echo '/path/to/a/control/article' | controlchan
    echo '@0303465234000000000000235AE000000002@' | controlchan
```

Note that in the (very, very unlikely) event that you need to process ihave/sendme control messages, be sure that logipaddr is set to false in inn.conf, because in this case controlchan needs a site name, not an IP address.

controlchan tries to report all log messages through syslog(3), unless connected to an interactive terminal. To enable syslog(3)'ing for versions of Perl prior to 5.6.0, you will need to have run h2ph on your system include files at some point (this is required to make "Sys::Syslog" work). If you have not done so, do this:

```
    cd /usr/include
    h2ph * sys/*
```

If you run FreeBSD, you will need to run the following in addition:

```
    h2ph machine/*
```

## OPTIONS
-c

By default, controlchan does not process articles whose Date or Injection-Date header fields are too far in the past (more than artcutoff days, as set in inn.conf) or one day in the future. It allows preventing a malicious replay of old control articles. Using the -c flag disables this check on the cutoff date.

-h

Gives usage information.

## HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. Converted to POD by Julien Elie.

## SEE ALSO
control.ctl(5), inn.conf(5).


ctlinnd

title: ctlinnd(8)

summary: Control the main InterNetNews daemon

text:
# ctlinnd(8)

## NAME
ctlinnd - Control the main InterNetNews daemon

## SYNOPSIS
ctlinnd [-hs] [-t timeout] [command [argument ...]]

## DESCRIPTION
ctlinnd sends a message to the control channel of innd(8), the main InterNetNews daemon.

In the normal mode of behavior, the message is sent to the server, which then performs the requested action and sends back a reply with a text message and an exit code for ctlinnd. If the server successfully performed the command, ctlinnd will print the reply on standard output and exit with a status of zero. If the server could not perform the command, it will direct ctlinnd to exit with a status of one. By default, ctlinnd will wait forever for a response from innd; this can be changed with the -t flag.

The "shutdown", "xabort", and "xexec" commands do not generate a reply, since they cause innd to exit. After these commands, ctlinnd will always exit silently with a status of zero.

## OPTIONS
-h

Prints a command summary. If a command is given along with the -h flag, only the usage for that command will be given.

-s

If the command was successful, don't print the output from innd.

-t timeout

Specifies how long to wait for the reply from the server, for commands other than "shutdown", "xabort", and "xexec". timeout is the number of seconds to wait. A value of zero says to wait forever, and a value less than zero says not to wait at all but just exit immediately with status zero. When waiting for a reply, ctlinnd will check every two minutes to be sure the server is still running, to make it less likely that ctlinnd will just hang. The default is zero, indicating that ctlinnd should wait forever.

## COMMANDS
Here is the complete list of supported commands. Note that nearly all commands have a fixed number of arguments. If a parameter may be an empty string, it is still necessary to pass the empty string to ctlinnd as an argument (specified in the shell as two adjacent quotes, like '').

addhist message-id arrival expires posted token

Add an entry to the history database for message-id. The angle brackets around message-id are optional. It should normally be protected from the shell with single quotes. arrival, expires, and posted should be the number of seconds since epoch and indicate when the article arrived, when it expires (via the Expires header field), and when it was posted (given in the Date header field), respectively. expires should be 0 if the article doesn't have an Expires header field. token is the storage API token for the article, and may be empty.

This command can only be used while the server is running, and will be rejected if the server is paused or throttled.

allow reason

Allow remote connections, reversing a prior "reject" command. reason must be the same text given to the "reject" command, or the empty string (which matches any reason).

begin site

Begin feeding site. The server will rescan the newsfeeds file to find the specified site and set up a news feed for it. If the site already existed, a "drop" for that site is done first. This command is forwarded; see "NOTES" below.

cancel message-id

Remove the article with the specified message-ID from the local system. This does not generate a cancel control message; it only affects the local system. The angle brackets around message-ID are optional. It should normally be protected from the shell with single quotes (and not double quotes). For instance:

```
    ctlinnd cancel 'test@foo.bar'

```

Note that the history database is updated with the specified Message-ID so if an article with the same Message-ID is afterwards received, it will be rejected; it is useful for rejecting spam before it arrives.

If the server is throttled manually, this command causes it to briefly open the history database. If the server is paused or throttled for any other reason, this command is rejected.

changegroup group status

The newsgroup group is changed so that its status (the fourth field in the active file) becomes status. This may be used to make an existing group moderated or unmoderated, for example. This command, unlike "newgroup" or "rmgroup", can only be used while the server is running, and will be rejected if the server is paused or throttled.

checkfile

Check the syntax of the newsfeeds file and display a message if any errors are found. The details of the errors are reported to syslog.

drop site

Flush and drop site from the server's list of active feeds. This command is forwarded; see "NOTES" below.

feedinfo site

Print detailed information about the state of the feed to site, or brief status about all feeds if site is the empty string.

flush site

Flush the buffer for the specified site. The action taken depends on the type of feed the site receives; see newsfeeds(5) for more information. This is useful when the site is being fed by a file and batching is about to start, or to cleanly shut down and respawn a channel feed. If site is an empty string, all sites are flushed and the active file and history database are also flushed to disk. This command is forwarded; see "NOTES" below. Flushing the innfeed channel feed is the recommended method of restarting innfeed to pick up new configuration. innd will spawn a new innfeed process while the old process shuts down cleanly.

flushlogs

Close the news and error log files and rename them to add ".old" to the file name, then open fresh news and error logs. The active file and history database are also flushed to disk. Exploder and process channels are reopened so that they properly take into account the new log files.

go reason

Re-open the history database and start accepting articles again, reversing a previous "pause" or "throttle" command. reason must be either the empty string or match the text that was given to the earlier "pause" or "throttle" command. If a "reject" command is in effect, this will also reverse it by doing the equivalent of an "allow" command if the reason matches reason. Likewise, if a "reserve" command had been given, this will clear the reservation if reason matches the text that was given to "reserve".

The history database is automatically closed on "throttle" or "pause" and reopened on "go", so the history database can be replaced during the pause or throttle without requiring an explicit "reload" command. If any other configuration files or the active file were modified, a "reload" command should be given to force the server to re-read those files.

If the server throttled itself because it accumulated too many I/O errors, this command will reset the error count.

If innd was not started with the -n y flag, this command also does the equivalent of a "readers" command with "yes" as the flag and reason as the text.

hangup channel

Close the socket for the specified incoming channel. This may be useful when an incoming connection appears to be hung (although innd will close idle connections automatically after a timeout, as set with peertimeout in inn.conf).

help [command]

Print a command summary for all commands, or just command if one is specified. This is equivalent to the -h option.

kill signal site

Signal signal is sent to the process underlying the specified site, which must be a channel or exploder feed. signal may be a numeric signal number or one of "hup", "int", or "term"; case is not significant.

logmode

Cause the server to log its current operating mode to syslog.

lowmark file

Reset the low water marks in the active file based on the contents of file. Each line in file must be of the form:

```
    group low-value

```

For example:

```
    comp.lang.c++ 243

```

This command is mostly used by news.daily to update the active file after nightly expiration.

mode

Print the server's operating mode as a multi-line summary of the parameters and the operating state. The parameters in the output correspond to command-line flags to innd and give the current settings of those parameters that can be overridden by command-line flags.

name channel

Print the name and relevant information for the given incoming or outgoing channel number, or for all channels if channel is an empty string. The response is formatted as:

```
    <name>:<number>:<type>:<idle>:<status>

```

where <name> is the name of the channel, <number> is its number (generally the same as the file descriptor assigned to it), <idle> is the idle time for an NNTP channel or the process ID for a process channel, and <status> is the status for NNTP channels.

The <type> field is one of the following values:

```
    control     Control channel for ctlinnd
    file        An outgoing file feed
    localconn   Local channel used by nnrpd and rnews for posting
    nntp        NNTP channel for remote connections
    proc        The process for a process feed
    remconn     The channel that accepts new remote connections

```

Channel status indicates whether the channel is paused or not. Nothing is shown unless the channel is paused, in which case "paused" is shown. A channel will be paused automatically if the number of remote connections for that label in incoming.conf is greater than max-connections within hold-time seconds.

newgroup group [status [creator]]

Create the specified newsgroup. The status parameter is the fourth field of the active file entry, as described in active(5). If it is not an equal sign, only the first character is used. creator should be the identity of the person creating the group. If the newsgroup already exists, this is equivalent to the "changegroup" command. creator, encoded in UTF-8 if given, may be omitted; if so, it will default to the newsmaster (as specified at configure time, normally "usenet"). status may also be omitted; if so, it will default to "y" (a normal, unmoderated group). The combination of defaults make it possible to use the text of the Control header field directly (although don't do this without checking the syntactic validity of the header field first).

This command can only be done while the server is running or throttled manually. It will update its internal state when a "go" command is sent. This command updates the active.times file as well. This command is forwarded; see "NOTES" below.

param letter value

Change the specified server parameter. letter is the innd command-line option to set and value is the new value. For example:

```
    ctlinnd param i 5

```

would direct the server to allow only five incoming connections. To enable or disable the action of the -n flag, use "n" for the letter and "y" or "n", respectively, for the value.

The supported values for letter are "a", "c", "H", "i", "l", "n", "o", "T", "t", and "X".

pause reason

Pause the server so that no incoming articles are accepted. No existing connections are closed, but the history database is closed. This should be used for short-term locks, such as when replacing the history database. If the server was not started with the -n y flag, this command also does the equivalent of a "readers" command with "no" as the flag and reason as the text, encoded in UTF-8.

perl flag

Enable or disable Perl filtering on every article received by innd. This command is only available if INN was built with Perl filtering support. If flag starts with "y", filtering is enabled; if it starts with "n", filtering is disabled. When filtering is disabled, if the filter_innd.pl Perl filter defined a function "filter_end", it will be called prior to the deactivation of the filter.

Note that enabling or disabling Perl filtering on every post received by nnrpd is parameterized with the perlfilter access parameter in readers.conf.

python flag

Enable or disable Python filtering on every article received by innd. This command is only available if INN was built with Python filtering support. If flag starts with "y", filtering is enabled; if it starts with "n", filtering is disabled.

readers flag text

Allow or disallow readers. If flag starts with the letter "n", then reading is disallowed by causing the server to pass text as the value of the -r flag to nnrpd. If flag starts with the letter "y" and text is either an empty string or the same string, encoded in UTF-8, that was used when reading was disabled, reading will be re-enabled. The advantage of this parameter over noreader in inn.conf is that it permits specifying a custom message.

This command has no effect if nnrpd is being run separately rather than spawned by innd.

reject reason

Remote connections (those that would not be handed off to nnrpd) are rejected with reason given as the explanation, encoded in UTF-8. Existing connections are not closed.

reload what reason

Update the in-memory copy of server configuration files. what identifies what should be reloaded, and reason is reported to syslog in the message noting the reload. There is no way to reload inn.conf, storage.conf, or other configuration files for the storage or overview backends. To pick up changes to those files, use "ctlinnd xexec innd" to restart innd.

If what is the empty string or the word "all", everything is reloaded. If it is the word "history", the history database is closed and re-opened. If it is the word "incoming.conf", the corresponding file is reloaded. If it is the word "active" or "newsfeeds", both the active and newsfeeds files are reloaded, which will also cause all outgoing feeds to be flushed and restarted.

If what is the word "filter.perl", the filter_innd.pl file is reloaded. (This file is however not available for reloading unless INN was compiled with Perl filtering support.) If the Perl filter defined a function "filter_before_reload", it will be called prior to re-reading filter_innd.pl. If the Perl function "filter_after_reload" is defined, it will be called after filter_innd.pl has been reloaded. Reloading the Perl filter does not enable filtering if it has been disabled; use "perl y" to do this instead. startup_innd.pl cannot be reloaded.

If what is the word "filter.python", the filter_innd.py file is reloaded. (This file is however not available for reloading unless INN was compiled with Python filtering support.) If a Python method named "filter_before_reload" exists, it will be called prior to re-reading filter_innd.py. If a Python method named "__init__" exists, it will be called after filter_innd.py has been reloaded. Reloading the Python filter does not enable filtering if it has been disabled; use "python y" to do this.

renumber group

Update the low water and high water marks for group in the active file based on the information in the overview database. Regardless of the contents of the overview database, the high water mark will not be decreased. (Decreasing it may cause duplicate article numbers to be assigned after a crash, which can cause serious problems with the tradspool storage method.) If group is the empty string, all newsgroups are renumbered. Renumber only works if overview data has been created (if enableoverview is set to true in inn.conf).

renumberlow file

Identical to the "lowmark" command.

reserve reason

Require the next "pause" or "throttle" command to use reason as its reason, encoded in UTF-8. This reservation is cleared by giving an empty string for the reason. This is used by programs like expire to coordinate pauses and throttles of the server and avoid trampling on other instances of themselves.

rmgroup group

Remove the specified newsgroup. The group is removed from the active file and its overview information is purged, making it immediately unavailable to readers. Unlike the "newgroup" command, this command does not update the active.times file. This command can only be done while the server is running or throttled manually. This command is forwarded; see "NOTES" below.

send feed text

The specified text is sent as a control line to the exploder feed.

shutdown reason

The server is shut down, with the specified reason recorded in the log and sent to all open connections. It is a good idea to send a "throttle" command first so that feeds can be shut down more gracefully. If Perl or Python filtering is compiled in and enabled, certain functions are called at "throttle" or "shutdown" (to save filter state to disk, for example). Consult the embedded filter documentation for details.

stathist (off | filename)

Enable or disable generation of history performance statistics. If the parameter is "off", no statistics are gathered. Otherwise, statistics are written to the specified file. A parser for this file is provided in the contrib tree of the INN distribution. See stathist in inn.conf(5) for information on how to set the default.

status (off | interval)

Adjust the frequency with which innd reports status information to syslog. Status reporting is turned off if "off" or 0 is given as the argument. Otherwise, status will be reported every interval seconds. See status in inn.conf(5) for information on how to set the default.

throttle reason

Close all existing incoming connections and outgoing feeds, and reject new connections. Close the history database. This should be used for long-term locks or for running a large number of "newgroup" and "rmgroup" commands without restarting all outgoing feeds between each one. (Note that changing the status of existing newsgroups when the server is throttled cannot be done.) If the server was not started with the -n y flag, then this command also does the equivalent of a "readers" command with "no" as the flag and reason as the text, encoded in UTF-8.

timer (off | interval)

Adjust the frequency with which innd reports performance information to syslog. Performance monitoring is turned off if "off" or 0 is given as the argument. Otherwise, statistics will be reported every interval seconds to syslog. See timer in inn.conf(5) for information on how to set the default.

trace item flag

Turn tracing on or off for the specified item. flag should start with the letter "y" or "n" to turn tracing on or off, respectively. If item starts with a number, tracing is set up for the specified innd channel, which must be an incoming NNTP feed. If it starts with the letter "i", general innd tracing is turned on or off. If it starts with the letter "n", future nnrpd processes spawned by "innd" will or will not be passed the -t flag, as appropriate. This will not affect any nnrpd processes already running, or nnrpd processes started by some means other than innd.

xabort reason

Log the specified reason and then abort. On most systems, this will cause innd to dump a core file. This is only useful for debugging.

xexec path

Shut down the server, but then rather than exiting, exec innd with all of its original arguments except for -r. path may be either "innd" or an empty string, both of which are equivalent. Any other value is an error. This is the easiest way to start a new copy of innd after upgrading or reload configuration files that can't be reloaded via the "reload" command.

## NOTES
In addition to being acted on by the server, certain commands can be forwarded to an appropriate child process. If the site receiving the command is an exploder (such as buffchan) or a funnel that feeds into an exploder, the command can be forwarded. In this case, the server will send a command line to the exploder that consists of the ctlinnd command name. If the site funnels into an exploder that has an asterisk ("*") in its "W" flag (see newsfeeds(5) for more information on feed specifications), the site name will be appended to the command; otherwise, no argument is appended.

## BUGS
ctlinnd uses Unix domain sockets on most systems to communicate with innd and is therefore limited by whatever maximum packet size the operating system imposes on Unix domain datagrams. This may mean that server replies are limited to 4 KB on some systems.

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

## SEE ALSO
active(5), active.times(5), buffchan(8), incoming.conf(5), innd(8), inn.conf(5), libinn_inndcomm(3), newsfeeds(5), nnrpd(8).


cvtbatch

title: cvtbatch(8)

text:
# cvtbatch(8)

## NAME
cvtbatch - Convert Usenet batch files to INN format

## SYNOPSIS
cvtbatch [-w items]

## DESCRIPTION
cvtbatch reads standard input as a sequence of lines, converts each line, and writes it to standard output. It is used to convert simple batch files that contain just the storage API token of an article to INN batch files that contain additional information about each article.

Each line is taken as a storage API token indicating a Usenet article. Only the first word of each line is parsed; anything following whitespace is ignored. Lines not starting with a valid token are also silently ignored.

If the input file consists of a series of message-IDs, then use grephistory with the -s flag piped into cvtbatch.

## OPTIONS
-w items

The -w flag specifies how each output line should be written. The items for this flag should be chosen from the "W" flag items as specified in newsfeeds(5). They may be chosen from the following set:

```
    b    Size of the article in bytes.
    f    Storage API token of the article (same as "n").
    m    Article message-ID.
    n    Storage API token of the article.
    t    Arrival time of the article as seconds since epoch.

```

The default is "nm", that is to say the storage API token followed by the message-ID of the article.

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

## SEE ALSO
grephistory(1), newsfeeds(5).


docheckgroups

title: docheckgroups(8)

text:
# docheckgroups(8)

## NAME
docheckgroups - Process checkgroups and output a list of changes

## SYNOPSIS
docheckgroups [-u] [include-pattern [exclude-pattern]]

## DESCRIPTION
docheckgroups is usually run by controlchan in order to process checkgroups control messages. It reads a list of newsgroups along with their descriptions on its standard input. That list should be formatted like the newsgroups(5) file: each line contains the name of a newsgroup followed by one or more tabulations and its description.

docheckgroups will only check the presence of newsgroups which match include-pattern (an egrep expression like "^comp\..*$" for newsgroups starting with "comp.") and which do not match exclude-pattern (also an egrep expression) except for newsgroups mentioned in the pathetc/localgroups file. This file is also formatted like the newsgroups(5) file and should contain local newsgroups which would otherwise be mentioned for removal. There is no need to put local newsgroups of hierarchies for which no checkgroups control messages are sent, unless you manually process checkgroups texts for them. Lines beginning with a hash sign ("#") are not taken into account in this file. All the newsgroups and descriptions mentioned in pathetc/localgroups are appended to the processed checkgroups.

If exclude-pattern is given, include-pattern should also be given before (you can use an empty string ("") if you want to include all the newsgroups). Be that as it may, docheckgroups will only check newsgroups in the top-level hierarchies which are present in the checkgroups.

Then, docheckgroups checks the active and newsgroups files and displays on its standard output a list of changes, if any. It does not change anything by default; it only points out what should be changed:

- Newsgroups which should be removed (they are in the active file but not in the checkgroups) and the relevant ctlinnd commands to achieve that;

- Newsgroups which should be added (they are not in the active file but in the checkgroups) and the relevant ctlinnd commands to achieve that;

- Newsgroups which are incorrectly marked as moderated or unmoderated (they are both in the active file and the checkgroups but their status differs) and the relevant ctlinnd commands to fix that;

- Descriptions which should be removed (they are in the newsgroups file but not in the checkgroups);

- Descriptions which should be added (they are not in the newsgroups file but in the checkgroups).

The output of docheckgroups can be fed into mod-active (it will pause the news server, update the active file accordingly, reload it and resume the work of the news server) or into the shell (commands for ctlinnd will be processed one by one). In order to update the newsgroups file, the -u flag must be given to docheckgroups.

When processing a checkgroups manually, it is always advisable to first check the raw output of docheckgroups. Then, if everything looks fine, use mod-active and the -u flag.

## OPTIONS
-u

If this flag is given, docheckgroups will update the newsgroups file: it removes obsolete descriptions and adds new ones. It also sorts this file alphabetically and improves its general format (see newsgroups(5) for an explanation of the preferred number of tabulations).

## EXAMPLES
So as to better understand how docheckgroups works, here are examples with the following active file:

```
    a.first 0000000000 0000000001 y
    a.second.announce 0000000000 0000000001 y
    a.second.group 0000000000 0000000001 y
    b.additional 0000000000 0000000001 y
    b.third 0000000000 0000000001 y
    c.fourth 0000000000 0000000001 y
```

the following newsgroups file (using tabulations):

```
    a.first             First group.
    a.second.announce   Announce group.
    a.second.group      Second group.
    b.third             Third group.
    c.fourth            Fourth group.
```

and the following localgroups file (using tabulations):

```
    b.additional        A local newsgroup I want to keep.
```

The checkgroups we process is in the file test which contains:

```
    a.first             First group.
    a.second.announce   Announce group. (Moderated)
    a.second.group      Second group.
    b.third             Third group.
    c.fourth            Fourth group.
```

If we run:

```
    cat test | docheckgroups
```

docheckgroups will output that a.second.announce is incorrectly marked as unmoderated and that its description is obsolete. Besides, two new descriptions will be mentioned for addition (the new one for a.second.announce and the missing description for b.additional -- it should indeed be in the newsgroups file and not only in localgroups). Now that we have checked the output of docheckgroups and that we agree with the changes, we run it with the -u flag to update the newsgroups file and we redirect the standard output to mod-active to update the active file:

```
    cat test | docheckgroups -u | mod-active
```

That's all!

Now, suppose we run:

```
    cat test | docheckgroups "^c\..*$"
```

Nothing is output (indeed, everything is fine for the c.* hierarchy). It would have been similar if the test file had only contained the checkgroups for the c.* hierarchy (docheckgroups would not have checked a.* and b.*, even if they had been in include-pattern).

In order to check both a.* and c.*, you can run:

```
    cat test | docheckgroups "^a\..*$|^c\..*$"
```

And if you want to check a.* but not a.second.*, you can run:

```
    cat test | docheckgroups "^a\..*$" "^a\.second\..*$"
```

In our example, docheckgroups will then mention a.second.announce and a.second.group for removal since they are in the active file (the same goes for their descriptions). Notwithstanding, if you do want to keep a.second.announce, just add this group to localgroups and docheckgroups will no longer mention it for removal.

## FILES
pathbin/docheckgroups

The Shell script itself used to process checkgroups.

pathetc/localgroups

The list of local newsgroups along with their descriptions.

## HISTORY
Documentation written by Julien Elie for InterNetNews.

## SEE ALSO
active(5), controlchan(8), ctlinnd(8), mod-active(8), newsgroups(5).


domain

title: domain(8)

summary: nnrpd domain resolver

text:
# domain(8)

## NAME
domain - nnrpd domain resolver

## SYNOPSIS
domain domain-name

## DESCRIPTION
This program can be used in readers.conf to grant access based on the subdomain part of the remote hostname. In particular, it only returns success if the remote hostname ends in domain-name. (A leading dot on domain-name is optional; even without it, the argument must match on dot-separated boundaries). The "username" returned is whatever initial part of the remote hostname remains after domain-name is removed. It is an error if there is no initial part (that is, if the remote hostname is exactly the specified domain-name).

## EXAMPLE
The following readers.conf(5) fragment grants access to hosts with internal domain names:

```
    auth internal {
        res: "domain .internal"
        default-domain: "example.com"
    }
    access internal {
        users: "*@example.com"
        newsgroups: example.*
    }
```

Access is granted to the example.* groups for all connections from hosts that resolve to hostnames ending in ".internal"; a connection from "foo.internal" would match access groups as "foo@example.com" identity.

## BUGS
It seems the code does not confirm that the matching part is actually at the end of the remote hostname (e.g., "domain: example.com" would match the remote host "foo.example.com.org" by ignoring the trailing ".org" part).

Does this resolver actually provide any useful functionality not available by using wildcards in the readers.conf(5) hosts parameter? If so, the example above should reflect this functionality.

## HISTORY
This documentation was written by Jeffrey M. Vinocur <jeff@litech.org>.

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


expire

title: expire(8)

text:
# expire(8)

## NAME
expire - Usenet article and history expiration program

## SYNOPSIS
expire [-iNnptx] [-d dir] [-f file] [-g file] [-h file] [-r reason] [-s size] [-v level] [-w number] [-z file] [expire.ctl]

## DESCRIPTION
expire scans the history(5)-format text file pathdb/history and uses the information recorded in it to purge itself of old news articles. Its behaviour depends on the setting of groupbaseexpiry in inn.conf.

When groupbaseexpiry is false, article expiration is primarily done by expire based on the expiration rules in expire.ctl that match the storage class of each article. The articles and the history entries are removed by expire, and then expireover does the additional cleanup of removing the overview database entries. History entries of expired articles are removed only if they are older than the number of days specified in the "/remember/" line in expire.ctl. Articles stored using a storage method that has self-expire functionality like CNFS are by default not affected by expire's primary behaviour (but see the -N flag to disable this).

When groupbaseexpiry is true, article expiration is primarily done by expireover based on the expiration rules in expire.ctl that match each newsgroup. Articles are removed from the news spool by expireover, and then expire does some additional cleanup to remove old history database entries.

For articles in self-expiring storage methods when groupbaseexpiry is set to false in inn.conf and the -N flag is not given, or for all articles when groupbaseexpiry is set to true, expire.ctl is ignored except the "/remember/" line; expire then only probes to see if the article still exists, and purges the relevant history entries if appropriate.

Regardless the setting of groupbaseexpiry, expireover should be run along with expire, usually via news.daily out of cron.

Note that expire never purges articles which do not match any entry in expire.ctl.

Also note that if groupbaseexpiry is true, the server needs an overview database in order to expire articles in storage backends that are not self-expiring. If you do not plan to have an overview database, it would then be better to only use self-expiring backends like CNFS, as the history entries will still get cleaned up by expire when it detects that an article no longer exists in that backend.

## OPTIONS
-d dir

If the -d flag is used, then the new history file and database is created in the specified directory dir. This is useful when the filesystem does not have sufficient space to hold both the old and new history files. When this flag is used, expire leaves the server paused and creates a zero-length file named after the new history file, with an extension of ".done" to indicate that it has successfully completed the expiration. The calling script should install the new history file and unpause the server. The -r flag should be used with this flag.

-f file

To specify an alternate history file, use the -f flag. This flag is valid when used with the -d flag, and the output will be written to the specified file. The default without -f is "history".

-g file

If the -g flag is given, then a one-line summary equivalent to the output of -v 1, except preceded by the current time, will be appended to the specified file.

-h file

To specify an alternate input text history file, use the -h flag. expire uses the old dbz database to determine the size of the new one. (If the -d flag is not used, the output filename will be the same as the input filename with an extension of ".n".) The default without the -h flag is pathdb/history.

-i

To ignore the old database, use the -i flag.

-N

The control file is normally ignored for articles in storage methods which have self-expire functionality. If the -N flag is used, expire still uses the control file for these articles. This parameter is only useful when groupbaseexpiry is set to false in inn.conf.

-n

If innd is not running, use the -n flag and expire will not send the "pause" or "go" commands. (For more details on the commands, see ctlinnd(8)). Note that expire only needs exclusive access for a very short time -- long enough to see if any new articles arrived since it first hit the end of the file, and to rename the new files to the working files.

-p

expire makes its decisions on the time the article arrived, as found in the history file. This means articles are often kept a little longer than with other expiration programs that base their decisions on the article's posting date. To use the article's posting date, use the -p flag.

-r reason

expire normally sends a "pause" command to the local innd daemon when it needs exclusive access to the history file, using the string "Expiring" as the reason. To give a different reason, use the -r flag. The process ID will be appended to the reason. When expire is finished and the new history file is ready, it sends a "go" command. See also the -n flag.

-s size

expire determines the optimal size of the new history file from the size of the old one. In case you want to force a specific size, use this flag to optimize the new history database for approximately size key-value pairs (i.e. lines in history). Accurately specifying the size will create a more efficient database. (The size should be the estimated eventual number of articles, typically the size of the old history file, in lines.)

-t

If the -t flag is used, then expire will generate a list of the tokens that should be removed on its standard output, and the new history file will be left in history.n, history.n.dir, history.n.index and history.n.hash. This flag is useful for debugging when used with the -n flag. Note that if the -f flag is used, then the name specified with that flag will be used instead of history.

-v level

The -v flag is used to increase the verbosity of the program, generating messages to standard output. The level should be a number, where higher numbers result in more output. Level one will print totals of the various actions done (not valid if a new history file is not written), level two will print a report on each individual file, while level five results in multiple lines of output for every history line processed.

-w number

Use the -w flag to "warp" time so that expire thinks it is running at some time other than the current time. The value should be a signed floating point number indicating the number of days to use as the offset.

-x

If the -x flag is used, then expire will not create any new history files. This is most useful when combined with the -n and -t flags to see how different expiration policies would change the amount of disk space used.

-z file

If the -z flag is used, then articles are not removed, but their names are appended to the specified file. See the description of delayrm in news.daily(8). If a filename is specified, it is taken as the control file and parsed according to the rules in expire.ctl. A single dash ("-") may be used to read the file from standard input. If no file is specified, the file pathetc/expire.ctl is read.

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

## SEE ALSO
ctlinnd(8), expire.ctl(5), expireover(8), history(5), inn.conf(5), innd(8), libinn_dbz(3), libinn_inndcomm(3), news.daily(8).