newslog

title: newslog(5)

summary: Description of INN log files

text:
# newslog(5)

## NAME
newslog - Description of INN log files

## DESCRIPTION
Most log files created by Usenet programs reside in the pathlog directory set in inn.conf and have a ".log" extension. Several versions are usually kept with an additional extension such as .1, .2, etc. -- the higher the number, the older the log. These old versions are stored in pathlog/OLD; they may be compressed and thus may have a ".1.gz", ".2.gz", etc. extension, up to ".nn.gz" where "nn" is the number of old logs kept by scanlogs which is set by logcycles in inn.conf.

The scanlogs script and related utilities are responsible for rotating and compressing these files. Some log files always have data (like news.notice), others only have data if there is a problem (like news.err), and others are only created if a particular program is used (like send-uucp.log used by send-uucp) or if a configuration parameter is set (like innfeed.log used by innfeed when debug-level is set in innfeed.conf).

Besides, the innstat script monitors the size of all log files.

Here are the log files used by INN:

control.log

This file maintains a count of the number of newgroup and rmgroup control messages seen for each newsgroup. The count is of the number of control messages with the indicated arguments, regardless if they were actually processed. All control arguments, including invalid ones, are counted. An example of lines which can be found in that log file is:

```
    3 Control: newgroup foo.bar moderated
    3 Control: rmgroup misc.removed
    1 Control: newgroup misc.created

```

This file is updated by tally.control, which is invoked by scanlogs if either one of these two log files exists in pathlog:

```
    newgroup.log
    rmgroup.log

```

These two log files contain a summary line describing the control message and the action taken by controlchan, followed by the article indented by four spaces, and a blank line. Whereas these files are rotated, control.log is not rotated so as to keep the count of seen control messages.

Note that other control log files are also rotated by scanlogs, if they exist, but their contents are not summarized. Here are their names:

```
    checkgroups.log
    default.log
    ihave.log
    miscctl.log
    sendme.log
    sendsys.log
    senduuname.log
    version.log

```

In order to create these files, the <type> and <action> fields of relevant control.ctl entries should be correctly set. For instance:

```
    Type            Action              Meaning
    ----            ------              -------
    all             log=miscctl         Log all messages by default.
    newgroup        doit=newgroup       Create group and log message.
    newgroup        log=newgroup        Log message.
    rmgroup         verify-*=rmgroup    PGP verify, remove group
                                        and log message.
    checkgroups     doit=checkgroups    Process and log message.

```

controlbatch.log

The controlbatch program appends all status messages to this file. It is rotated by scanlogs.

errlog

This file contains the standard output and standard error of any program spawned by innd, such as channel feeds configured in newsfeeds. This file should normally be empty. scanlogs will print the 50 first lines of this log file if it is non-empty so that they appear in daily Usenet reports generated by news.daily. Then, scanlogs rotates this log file.

expire.log

By default, when news.daily is going to expire old news articles, it writes the name of the program it invokes, followed by "start" and the time it has started. Any output from that program is then written, indented by four spaces. Then, the name of the program is written, followed by "end" and the time it has ended. Programs called, if needed, are in order: expireover, ctlinnd (with the "lowmark" option), expirerm and expire. Removed articles are listed in expire.list and low marks for each newsgroup (that is to say the number of the oldest article available in the newsgroup) in expire.lastlowmark.

After the expiry process, scanlogs rotates expire.log.

innfeed.log

When debug-level is set in innfeed.conf, innfeed appends debugging messages to this file. Note that the name of this file can be changed with the log-file parameter in innfeed.conf. Be that as it may, the right log file is rotated by scanlogs. Additionally, the innfeed-delayed.conf file is also looked at, to find another possible log file to rotate when delayer(1) is used with innfeed.

innfeed also logs its status in innfeed.status (or the name set in status-file) if gen-html is set to false but this log file is not processed by scanlogs.

news

This file logs articles received by innd. Typical lines are:

```
    Aug 25 13:37:41.839 + news.server.fr <cancel.4066@foo.com>
        1658 a.peer other.server.org inpaths!
    Aug 25 13:37:41.839 c news.server.fr <cancel.4066@foo.com>
        Cancelling <m070725@foo.com>
    Aug 25 13:37:54.638 - a.peer <23k82@bar.net> 437 Poison newsgroup

```

The first one indicates that an article from "news.server.fr" has been accepted ("+"). Its Message-ID is "<cancel.4066@foo.com>" and we will send the article to two peers ("a.peer" and "other.server.org", as specified in newsfeeds) and "inpaths!" (see ninpaths for more details about it). The second line mentions that this previous article is a cancel message ("c") for "<m070725@foo.com>" and that it has been processed (indeed, controlchan processes all control articles except for cancels which are handled by innd). The third line indicates that the article whose Message-ID is "<23k82@bar.net>" has been rejected ("-") because it is posted to a poison newsgroup (a Perl or a Python filter located in pathfilter must have brought that reject along).

See the "LOGGING" section of the innd(8) man page for more information about the format of this log file.

innreport summarizes the rejected articles reported in this file and scanlogs rotates it.

news.crit

All critical error messages issued by innd are appended to this file via syslog. This log file should normally be empty. scanlogs will print the first 50 lines of this log file if it is non-empty so that they appear in daily Usenet reports generated by news.daily. Then, scanlogs rotates this log file. You should have the following line in your system syslog.conf file, using a tab character for the delimiter:

```
    news.crit           <pathlog>/news.crit

```

(A typical entry is shown; it should agree with pathlog in inn.conf and be tab-delimited.)

news.err

All major error messages issued by innd are appended to this file via syslog. This log file should normally be empty. scanlogs will print the first 50 lines of this log file if it is non-empty so that they appear in daily Usenet reports generated by news.daily. Then, scanlogs rotates this log file. You should have the following line in your system syslog.conf file, using a tab character for the delimiter:

```
    news.err            <pathlog>/news.err

```

(A typical entry is shown; it should agree with pathlog in inn.conf and be tab-delimited.)

news.notice

All standard error messages and status messages issued by innd, innfeed, nnrpd and some other programs are appended to this file via syslog. scanlogs uses the Perl script innreport to summarize this file. innreport will also print the first max_unknown unknown lines of this log file if such unrecognized lines are found in news.notice so that they appear in daily Usenet reports generated by news.daily. This parameter can be set in innreport.conf. Then, scanlogs rotates this log file. You should have the following line in your system syslog.conf file, using a tab character for the delimiter:

```
    news.notice         -<pathlog>/news.notice

```

(A typical entry is shown; it should agree with pathlog in inn.conf and be tab-delimited.)

The minus sign as the first character for the path to news.notice instructs syslogd not to synchronize the log file to disk every time there is a new log entry (it otherwise degrades performance). Depending on the syslog daemon you are using, log synchronization may already be disabled by default (that is for instance the case for rsyslogd or syslog-ng).

nntpsend.log

The nntpsend program appends all status messages to this file. It is rotated by scanlogs.

perl-nocem.log

The perl-nocem program appends all status messages to this file if the syslog facility is not available or the -l flag is passed to perl-nocem (otherwise, the syslog facility is used in which case status messages are appended to a file usually named news.notice in pathlog). The perl-nocem.log file is processed by innreport and rotated by scanlogs.

send-ihave.log

The send-ihave program appends all status messages to this file. It is rotated by scanlogs.

send-uucp.log

The send-uucp program appends all status messages to this file. It is rotated by scanlogs.

unwanted.log

This log maintains a count of the number of articles that were rejected because they were posted to newsgroups that do not exist at the local site. This file is updated by innreport while processing the news.notice log file and it is maintained in reverse numeric order (the most popular rejected group first). This file is not rotated so as to keep the count of the articles posted to newsgroups which are absent from the active file of the news server. Note that logtrash has to be set to true in inn.conf for this file to be generated.

Finally, these files are also rotated by scanlogs, if they exist, but their contents are not summarized. Here are their names:

```
    badcontrol.log
    badpgp.log
    failedpgp.log
```

They can be used by programs which PGP verify articles.

## HISTORY
Written by Landon Curt Noll <chongo@toad.com> and Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten and converted to POD by Julien Elie.

## SEE ALSO
control.ctl(5), ctlinnd(8), expire(8), expireover(8), expirerm(8), inn.conf(5), innd(8), innfeed.conf(5), innreport(8), innreport.conf(5), news.daily(8), nnrpd(8), nntpsend(8), scanlogs(8), send-ihave(8), send-uucp(8), syslog.conf(5), tally.control(8).


nnrpd.track

package: inn

title: nnrpd.track(5)

summary: Specify hosts to be tracked by nnrpd

text:
# nnrpd.track(5)

## NAME
nnrpd.track - Specify hosts to be tracked by nnrpd

## DESCRIPTION
This file, which is located in pathetc, specifies which hosts are to have their activities recorded during an nnrpd session. The nnrpd server reads it when first spawned by innd, provided readertrack in inn.conf is true; otherwise this file is not used.

Entries consist of one host specification per line, each line having two fields, separated by a colon:

```
    host:identity
```

The first field is either one of the FQDNs of a host, or a domain name (in the form "*.domain.com").

The second field is simply a segment of text which may be used to more easily identify the client, typically an e-mail address or other identifying mark. Each post of tracked hosts will have an entry associated with identity in the log message recorded to the pathlog/tracklogs directory, and every posted article will be saved in the pathlog/trackposts directory.

An example of nnrpd.track file is:

```
    nasty.foo.com:nasty@foo.com
    *.bar.com:VeryNastyClient
```

## HISTORY
Written by Steve Carrie <stephenc@uk.uu.net> for InterNetNews. Rewritten into POD by Julien Elie.

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


nntpsend.ctl

title: nntpsend.ctl(5)

summary: List of sites to feed via nntpsend

text:
# nntpsend.ctl(5)

## NAME
nntpsend.ctl - List of sites to feed via nntpsend

## DESCRIPTION
The file pathetc/nntpsend.ctl specifies the default list of sites to be fed by nntpsend. Comments begin with a number sign ("#") and continue through the end of the line. Blank lines and comments are ignored. All other lines should consist of four fields separated by a colon.

The first field is the name of the site as specified in the newsfeeds file.

The second field should be the hostname or IP address of the remote site.

The third field, if non-empty, specifies the default head truncation size of the batch file. If this field is empty, no truncation is performed. This field may be of the form "maxsize-truncsize", in which case it is passed to shrinkfile as "-m maxsize -s truncsize"; otherwise it is of the form "truncsize", in which case it is passed as "-s truncsize".

The fourth field specifies some default flags passed to innxmit. Note that the flag -a is always given to innxmit and need not appear here. If no -t flag is given in this field or on the nntpsend command line, "-t 180" will be given to innxmit.

See nntpsend(8) for an example of nntpsend.ctl config file.

## HISTORY
Written by Landon Curt Noll <chongo@toad.com> for InterNetNews. Converted to POD by Julien Elie.

## SEE ALSO
innxmit(8), newsfeeds(5), nntpsend(8), shrinkfile(1).


ovdb

title: ovdb(5)

summary: Overview storage method for INN

text:
# ovdb(5)

## NAME
ovdb - Overview storage method for INN

## DESCRIPTION
The ovdb overview is a storage method that uses the Berkeley DB library to store overview data. It requires version 4.4 or later of the Berkeley DB library (4.7+ is recommended because older versions suffer from various issues).

The ovdb overview method makes use of the full transaction/logging/locking functionality of the Berkeley DB environment. Berkeley DB may be downloaded from <https://www.oracle.com/database/technologies/related/berkeleydb.html> and is needed to build the ovdb backend.

This method comes with a support utility which permits the manipulation of overview information. See ovdb_stat(8) for more details.

## UPGRADING
There are several versions of the ovdb storage method:

- Version 1, the initial version shipped with INN 2.3.0 up to INN 2.3.5.

- Version 2, with improved performance, since INN 2.4.0.

- Version 3, corresponding to version 2 with compression enabled, starting with INN 2.5.0.

If you have a database created with a previous version of ovdb, your database will need to be upgraded using ovdb_init. See the ovdb_init(8) man page for upgrade instructions, as well as the "COMPRESSION" section below.

Note that when the Berkeley DB library is updated to a newer version, the ovdb database also needs being upgraded.

## INSTALLATION
If the Berkeley DB library is found at configure time, INN will be built with Berkeley DB support unless the --without-bdb flag is explicitly passed to configure. By default, configure will search for Berkeley DB in standard locations; there will be a message in the configure output indicating the pathname that will be used.

You can override this pathname by adding a path to the option, for instance --with-bdb=/usr/BerkeleyDB.4.4. This directory is expected to have subdirectories include and lib (lib32 and lib64 are also checked), containing respectively db.h, and the library itself. In case non-standard paths to the Berkeley DB libraries are used, one or both of the options --with-bdb-include and --with-bdb-lib can be given to configure with a path.

The ovdb database may take up more disk space for a given spool than the other overview methods. Plan on needing at least 1.1 KB for every article in your spool (not counting crossposts). So, if you have 5 million articles, you'll need at least 5.5 GB of disk space for ovdb. With compression enabled, this estimate changes to 0.9 KB per article, so you'll need at least 4.5 GB of disk space for 5 million articles. See the "COMPRESSION" section below. Plus, you'll need additional space for transaction logs: at least 100 MB. By default, the transaction logs go in the same directory as the database. To improve performance, they can be placed on a different disk -- see the "DB_CONFIG" section.

## CONFIGURATION
To enable the ovdb overview method, set the ovmethod parameter in inn.conf to "ovdb". The ovdb database is stored in the directory specified by the pathoverview parameter in inn.conf. This is the "DB_HOME" directory. To start out, this directory should be empty (other than an optional DB_CONFIG file; see "DB_CONFIG" for details), and innd (or makehistory) will create the files as necessary in that directory. Also, make sure the directory is owned by the news user.

Other parameters for configuring ovdb are in the ovdb.conf configuration file. The following parameters can be set in that file:

compress

If INN was compiled with zlib, and this compress parameter is true, ovdb will compress overview records that are longer than 600 bytes. See the "COMPRESSION" section below.

cachesize

Size of the memory pool cache, in kilobytes. The cache will have a backing store file in the DB directory which will be at least as big. In general, the bigger the cache, the better. Use "ovdb_stat -m" to see cache hit percentages. To make a change of this parameter take effect, shut down and restart INN (be sure to kill all of the nnrpd processes when shutting down). Default is 8000 (KB), which is adequate for small to medium-sized servers. Large servers will probably need at least 20000 (KB).

ncache

Number of regions across which to split the cache. The region size is equal to cachesize divided by ncache. Default is 1 for ncache, that is to say the cache will be allocated contiguously in memory.

numdbfiles

Overview data is split between this many files. Currently, innd will keep all of the files open, so don't set this too high or innd may run out of file descriptors. nnrpd only opens one at a time, regardless. May be set to one, or just a few, but only do that if your OS supports large (> 2 GB) files. Changing this parameter has no effect on an already-established database. Default is 32.

txn_nosync

If txn_nosync is set to false, Berkeley DB flushes the log after every transaction. This minimizes the number of transactions that may be lost in the event of a crash, but results in significantly degraded performance. Default is true, in which case ovdb_monitor flushes the transaction logs every 30 seconds.

useshm

If useshm is set to true, Berkeley DB will use shared memory instead of mmap for its environment regions (cache, lock, etc). With some platforms, this may improve performance. Default is false.

shmkey

Sets the shared memory key used by Berkeley DB when useshm is true. Berkeley DB will create several (usually 5) shared memory segments, using sequentially numbered keys starting with "shmkey". Choose a key that does not conflict with any existing shared memory segments on your system. Default is 6400.

pagesize

Sets the page size for the DB files (in bytes). Must be a power of 2. Best choices are 4096 or 8192. The default is 8192. Changing this parameter has no effect on an already-established database.

minkey

Sets the minimum number of keys per page. See the Berkeley DB documentation for more information. Default is based on page size and whether compression is enabled:

```
   default_minkey = MAX(2, pagesize / 2600) if compress is false
   default_minkey = MAX(2, pagesize / 1500) if compress is true

```

The lowest allowed minkey is 2. Setting minkey higher than the default is not recommended, as it will cause the databases to have a lot of overflow pages. Changing this parameter has no effect on an already-established database.

maxlocks

Sets the Berkeley DB lk_max parameter, which is the maximum number of locks that can exist in the database at the same time. Default is 4000.

nocompact

The nocompact parameter affects the behaviour of expireover. The expireover function in ovdb can do its job in one of two ways: by simply deleting expired records from the database; or by re-writing the overview records into a different location leaving out the expired records. The first method is faster, but it leaves 'holes' that result in space that can not immediately be reused. The second method 'compacts' the records by rewriting them. If this parameter is set to 0, expireover will compact all newsgroups; if set to 1, expireover will not compact any newsgroups; and if set to a value greater than one, expireover will only compact groups that have less than that number of articles.

Experience has shown that compacting has minimal effect (other than making expireover take longer) so the default is 1. This parameter will probably be removed in the future.

readserver

When the readserver parameter is set to false, each nnrpd process directly accesses the Berkeley DB environment. The process of attaching to the database (and detaching when finished) is fairly expensive, and can result in high loads in situations when there are lots of reader connections of relatively short duration. When the readserver parameter is set to true, the nnrpd processes will access overview via a helper server (ovdb_server -- which is started by ovdb_init). All ovdb reads will then be funnelled through a single process with a cleaner interface to the underlying Berkeley DB database. This will result in cleaner shutdowns for the database, improving stability and avoiding deadlocks, timing issues and corrupted databases. That's why you should try to set this parameter to true if you are experiencing any instability in the ovdb overview method.

Default value is true.

numrsprocs

This parameter is only used when readserver is true. It sets the number of ovdb_server processes. As each ovdb_server can process only one transaction at a time, running more servers can improve reader response times. Default is 5.

maxrsconn

This parameter is only used when readserver is true. It sets a maximum number of readers that a given ovdb_server process will serve at one time. This means the maximum number of readers for all of the ovdb_server processes is (numrsprocs * maxrsconn). This does not limit the actual number of readers, since nnrpd will fall back to opening the database directly if it can't connect to an ovdb_server. Default is 0, which means an unlimited number of connections is allowed.

## COMPRESSION
The ovdb storage method has the ability to compress overview data before it is stored into the database. In addition to consuming less disk space, compression keeps the average size of the database keys smaller. This in turn increases the average number of keys per page, which can significantly improve performance and also helps keep the database more compact. This feature requires that INN be built with zlib. Only records larger than 600 bytes get compressed, because that is the point at which compression starts to become significant.

If compression is not enabled (either from the compress option in ovdb.conf or INN was not built with zlib support), the database will be backward compatible with older versions of ovdb. However, if compression is enabled, the database is marked with a newer version that will prevent older versions of ovdb from opening the database.

You can upgrade an existing database to use compression simply by setting compress to true in ovdb.conf. Note that existing records in the database will remain uncompressed; only new records added after enabling compression will be compressed.

If you disable compression on a database that previously had it enabled, new records will be stored uncompressed, but the database will still be incompatible with older versions of ovdb (and will also be incompatible with this version of ovdb if INN was not built with zlib support). So to downgrade to a completely uncompressed database, you will have to rebuild the database using makehistory.

## DB_CONFIG
A file called DB_CONFIG may be placed in the database directory (pathoverview in inn.conf) to customize where the various database files and transaction logs are written. By default, all of the files are written in the "DB_HOME" directory. One way to improve performance is to put the transaction logs on a different disk. To do this, put:

```
    DB_LOG_DIR /path/to/logs
```

in the DB_CONFIG file. If the pathname you give starts with a "/", it is treated as an absolute path; otherwise, it is relative to the "DB_HOME" directory. Make sure that any directories you specify exist and have proper ownership/mode before starting INN, because they won't be created automatically. Also, don't change the DB_CONFIG file while anything that uses ovdb is running.

Another thing that you can do with this file is to split the overview database across multiple disks. In the DB_CONFIG file, you can list directories that Berkeley DB will search when it goes to open a database.

For example, let's say that you have pathoverview set to /mnt/overview and you have four additional file systems created on /mnt/ovX. You would create a file /mnt/overview/DB_CONFIG containing the following lines:

```
    set_data_dir /mnt/overview
    set_data_dir /mnt/ov1
    set_data_dir /mnt/ov2
    set_data_dir /mnt/ov3
    set_data_dir /mnt/ov4
```

Distribute your ovNNNNN files into the four filesystems (say, 8 each). When called upon to open a database file, the db library will look for it in each of the specified directories (in order). If said file is not found, one will be created in the first of those directories.

Whenever you change DB_CONFIG or move database files around, make sure all news processes that use the database are shut down first (including nnrpd processes).

The DB_CONFIG functionality is part of Berkeley DB itself, rather than something provided by ovdb. See the Berkeley DB documentation for complete details for the version of Berkeley DB that you're running.

## RUNNING
When starting the news system, rc.news will invoke the ovdb_init program. See the ovdb_init(8) man page for information about the tasks it performs. ovdb_init must be run before using the database.

And when stopping INN, rc.news kills the ovdb_monitor processes after the other INN processes have been shut down.

## DIAGNOSTICS
Problems relating to ovdb are logged to news.err with "OVDB" in the error message.

INN programs that use overview will fail to start up if the ovdb_monitor processes aren't running. Be sure to run ovdb_init before running anything that accesses overview.

Also, INN programs that use overview will fail to start up if the user running them is not the news user.

If a program accessing the database crashes, or otherwise exits uncleanly, it might leave a stale lock in the database. This lock could cause other processes to deadlock on that stale lock. To fix this, shut down all news processes (using "kill -9" if necessary) and then restart. ovdb_init should perform a recovery operation which will remove the locks and repair damage caused by killing the deadlocked processes.

## FILES
pathetc/inn.conf

The ovmethod and pathoverview parameters are relevant to ovdb.

pathetc/ovdb.conf

Optional configuration file for tuning. See "CONFIGURATION" above.

pathoverview

Directory where the database goes. Berkeley DB calls it the "DB_HOME" directory.

pathoverview/DB_CONFIG

Optional file to configure the layout of the database files.

pathrun/ovdb.sem

A file that gets locked by every process that is accessing the database. This is used by ovdb_init to determine whether the database is active or quiescent.

pathrun/ovdb_monitor.pid

Contains the process ID of ovdb_monitor.

## TO DO
Implement a way to limit how many databases can be open at once (to reduce file descriptor usage); maybe using something similar to the cache code in legacy ov3.c file.

## HISTORY
Written by Heath Kehoe <hakehoe@avalon.net> for InterNetNews.

## SEE ALSO
inn.conf(5), innd(8), makehistory(8), nnrpd(8), ovdb_init(8), ovdb_monitor(8), ovdb_stat(8).

Berkeley DB documentation: in the docs directory of the Berkeley DB source distribution, or on the Oracle Berkeley DB web page (<https://www.oracle.com/database/technologies/related/berkeleydb.html>).


ovsqlite

title: ovsqlite(5)

summary: SQLite\-based overview storage method for INN

text:
# ovsqlite(5)

## NAME
ovsqlite - SQLite-based overview storage method for INN

## DESCRIPTION
This method uses SQLite to store overview data. It requires version 3.8.2 or later of the SQLite library (3.20.0+ recommended).

SQLite source, documentation, etc. are available at <https://www.sqlite.org/>. Ones of the stated goals of the SQLite file format are long-term stability and compatibility, which make that storage method a perfect choice to store overview data.

Only one protocol version of the ovsqlite storage method currently exists, implemented since INN 2.7.0.

This method comes with a support utility (ovsqlite-util) and a Perl module ("INN::ovsqlite_client") which permit accessing and manipulating overview information. See their manual pages for more details about their possibilities.

## INSTALLATION
The configure script will automatically enable ovsqlite support if it finds the SQLite library. If the library isn't installed in a standard location, you may have to specify the --with-sqlite3 option to help configure find it. For complicated cases, you can use separate --with-sqlite3-include and --with-sqlite3-lib options. Finally, if you don't want ovsqlite support even when your system has the SQLite library, you can use the --without-sqlite3 option.

If you have a recent Linux installation, SQLite is most likely already installed. You may have to install a separate package with a name similar to "libsqlite3-dev" to get the required header files.

Plan on needing at least 0.93 KB for every article in your spool (not counting crossposts). So, if you have 5 million articles, you'll need at least 4.65 GB of disk space for ovsqlite. With compression enabled, this estimate changes to 0.4 KB per article, so you'll need at least 2 GB of disk space for 5 million articles. Plus, you'll need additional space for transaction logs (a few MB).

## CONFIGURATION
To select ovsqlite as your overview method, set the ovmethod parameter in inn.conf to "ovsqlite". The database file will be created in the directory specified by the pathoverview parameter in inn.conf. Restart INN to take the change into account (after having rebuilt your existing overview with makehistory, if needed).

These additional parameters are read from the ovsqlite.conf configuration file:

cachesize

The SQLite in-memory page cache size in kilobytes. The default value is left up to the SQLite library and seems to be stable at 2000 KB.

compress

If INN was built with zlib support and this parameter is true, ovsqlite will compress overview records whenever this saves space. This parameter is consulted only when creating a new database. Enabling compression saves about 55 % of disk space on standard overview data. The default value is false.

pagesize

The SQLite database page size in bytes. Must be a power of 2, minimum 512, maximum 65536. Appropriate values include the virtual memory page size and the filesystem allocation block size. This parameter is consulted only when creating a new database. The default value is left up to the SQLite library and varies between versions.

transrowlimit

The maximum number of article rows that can be inserted or deleted in a single SQL transaction. The default value is 10000 articles.

transtimelimit

The maximum SQL transaction lifetime in seconds. The default value is 10 seconds.

A transaction occurs every transrowlimit articles or transtimelimit seconds, whichever is smaller. You are encouraged to keep the default value for row limits and, instead, adjust the time limit according to how many articles your news server usually accepts per second during normal operation (you can find statistics about incoming articles in your daily Usenet reports). Inserting or deleting a database row within a transaction is very fast whereas committing a transaction is slow, especially on rotating storage. Setting transaction limits too low leads to poor performance. When rebuilding overview data, it may be worth temporarily raising these values on systems with slow CPU or rotating storage (for instance, multiply by 10 the default values). Performance won't change much on fast systems.

## RUNNING
All overview database access goes through the ovsqlite-server daemon. For ordinary operation, rc.news will start and stop it automatically. If you want to touch the overview database while innd isn't running, you'll have to start ovsqlite-server manually first. See ovsqlite-server(8).

## HISTORY
Initial implementation of ovsqlite written by Bo Lindbergh <2bfjdsla52kztwejndzdstsxl9athp@gmail.com> for InterNetNews.

## SEE ALSO
INN::ovsqlite_client(3pm), inn.conf(5), makehistory(8), ovsqlite-server(8), ovsqlite-util(8), rc.news(8).


passwd.nntp

title: passwd.nntp(5)

text:
# passwd.nntp(5)

## NAME
passwd.nntp - Passwords for connecting to remote NNTP servers

## DESCRIPTION
The file pathetc/passwd.nntp contains host / name / password triplets for use when authenticating client programs to NNTP servers. This file is normally interpreted by "NNTPsendpassword()" in libinn(3). Blank lines and lines beginning with a number sign ("#") are ignored. All other lines should consist of three or four fields separated by colons:

```
    host:name:password
    host:name:password:style
```

The first field is the name of a host, and is matched in a case-insensitive manner. (No detailed matching, such as comparing IP addresses, is done.)

The second field is a user name, and the third is a password. If either the username or password is empty, then that portion of the authentication will not occur. (For example, a server may require only a username, in which case the password is not necessary. Note that a username is mandatory with AUTHINFO USER/PASS.)

The optional fourth field specifies the type of authentication to use. At present, the only recognized "authentication style" is "authinfo"; this is also the default. It means that AUTHINFO USER/PASS commands are used to authenticate to the remote host. (These NNTP commands are described in RFC 4643.)

For example:

```
    mit.edu:bbn:mypasswd
    uunet.uu.net:bbn:yoyoma:authinfo
```

This file should not be world-readable.

actsync, getlist, inews, innxbatch, innxmit, nnrpd, nntpget and rnews make use of passd.nntp when needing to connect to a remote server.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.

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


readers.conf

title: readers.conf(5)

text:
# readers.conf(5)

## NAME
readers.conf - Access control and configuration for nnrpd

## IN A NUTSHELL
The readers.conf file parameters who is allowed to connect as a news reader and what they're allowed to do after they connect. Bear in mind that in readers.conf, authentication and authorization are configured in different blocks. First, a user is authenticated, and assigned an identity (in an "auth" block). Then this identity is authorized to access certain newsgroups with certain rights (in an "access" block).

As for authentication, your "auth" block for password users could look like this:

```
    auth "foreignokay" {
        auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
        default: "<unauthenticated>"
    }
```

See the documentation of the -f flag in the ckpasswd(8) man page for how to generate passwords and make use of this newsusers file.

This way, with the "foreignokay" authentication block, a user successfully authenticated as user "myusername" will be assigned the identity "myusername". If authentication fails, it will be assigned the default identity "<unauthenticated>" that will later be checked in "access" blocks.

Authentication blocks are checked from the last one in the readers.conf file to the first one (bottom up). As soon as one matches, the corresponding identity is assigned to the user.

As for authorization, let's do something in an "access" block for people successfully authenticated with passwords:

```
    access "authenticatedpeople" {
        users: "*"
        newsgroups: "*,!junk,!control,!control.*"
    }
```

And then something like one of the following two, depending on whether unauthenticated users get any access:

```
    access "restrictive" {
        users: "<unauthenticated>"
        newsgroups: "!*"
    }
    access "readonly" {
        users: "<unauthenticated>"
        read: "local.*"
        post: "!*"
    }
```

Please note that the "authenticatedpeople" block must appear in readers.conf before "restrictive" or "readonly" blocks because access blocks are checked from the last one in the readers.conf file to the first one (bottom up). As soon as one matches the identity previously assigned by an authentication block, it is chosen. The "authenticatedpeople" access block matches every user that has not been assigned "<unauthenticated>" as identity.

More examples and features are detailed below in this man page (notably without any password file, with PAM, with Perl or Python hooks).

You don't need to reload anything after modifying readers.conf; every time a news client connects to the server, a new nnrpd process is spawned and reads its configuration from disk. Nonetheless, after any changes, you can run "inncheck" to perform basic syntax checks against the modified readers.conf file.

## DESCRIPTION
readers.conf in pathetc specifies access control for nnrpd(8). It controls who is allowed to connect as a news reader and what they're allowed to do after they connect. nnrpd reads this file every time a news client connects to the server, even when running in daemon mode with -D, which means that any changes on this file take effect immediately on all subsequent connections. (The location of readers.conf in pathetc is only the default; the same format applies to any file specified with "nnrpd -c".)

There are two types of entries in readers.conf: parameter/value pairs and configuration groups. Blank lines and anything after a number sign ("#") are ignored, unless the character "#" is escaped with "\". The maximum number of characters on each line is 8,191.

Parameter/value pairs consist of a keyword immediately followed by a colon, at least one whitespace character, and a value. The case of the parameter is significant (parameter should generally be in all lowercase), and a parameter may contain any characters except colon, "#", and whitespace. An example:

```
    hosts: *.example.com
```

Values that contain whitespace should be quoted with double quotes, as in:

```
    hosts: "*.example.com, *.example.net"
```

If the parameter does not contain whitespace, such as:

```
    hosts: *.example.com,*.example.net
```

it's not necessary to quote it, although you may wish to anyway for clarity.

There is no way to continue a line on the next line, and therefore no way to have a single parameter with a value longer than about 8,180 characters.

Many parameters take a boolean value. For all such parameters, the value may be specified as "true", "yes", or "on" to turn it on and may be any of "false", "no", or "off" to turn it off. The case of these values is not significant.

There are two basic types of configuration groups: auth and access. The auth group provides mechanisms to establish the identity of the user, who they are. The access group determines, given the user's identity, what that user is permitted to do. Writing a readers.conf file for your setup is a two-step process: first assigning an identity to each incoming connection using auth groups, and then giving each identity appropriate privileges with access group. We recommend not intermingling auth groups and access groups in the config file; it is often more sensible (in the absence of the key parameter) to put all of the auth groups first, and all of the access groups below.

A user identity, as established by an auth group, looks like an e-mail address if a domain is specified (like "<username>@<domain>") or otherwise just "<username>".

If nnrpdauthsender is set in inn.conf, the user identity is also put into the Sender header field of posts made by that user. See the documentation of that option in inn.conf(5) for more details.

An auth group definition looks like:

```
    auth <name> {
        hosts: <host-wildmat>
        auth: <auth-program>
        res: <res-program>
        default: <defuser>
        default-domain: <defdomain>
        # ...possibly other settings
    }
```

The <name> is used as a label for the group and is only for documentation purposes. (If your syslog configuration records the "news.debug" facility, the <name> will appear in the debugging output of nnrpd. Examining that output can be very helpful in understanding why your configuration doesn't do what you expect it to.)

A given auth group applies only to hosts whose name or IP address matches the wildmat expression given with the hosts parameter (comma-separated wildmat expressions are allowed, but "@" is not supported). Rather than wildmat expressions, you may also use CIDR notation to match any IP address in a netblock; for example, "10.10.10.0/24" will match any IP address between 10.10.10.0 and 10.10.10.255 inclusive.

If compiled against the TLS/SSL or SASL libraries, an auth group with the require_encryption parameter set to true only applies if the incoming connection is using an encryption layer, either from the beginning if the -S flag was passed to nnrpd, or after a successful use of STARTTLS, or after a successful authentication using an SASL mechanism which negotiates an encryption layer.

For any connection from a host that matches that wildmat expression or netblock, each <res-program> (multiple res lines may be present in a block; they are run in sequence until one succeeds), if any, is run to determine the identity of the user just from the connection information. If all the resolvers fail, or if the res parameter isn't present, the user is assigned an identity of "<defuser>@<defdomain>"; in other words, the values of the default and default-domain parameters are used. If <res-program> only returns a username, <defdomain> is used as the domain.

If the user later authenticates via the AUTHINFO USER/PASS commands, the provided username and password are passed to each <auth-program> (multiple auth, perl_auth, or python_auth lines may be present in a block; they are run in sequence until one succeeds), if any. If one succeeds and returns a different identity than the one assigned at the time of the connection, it is matched against the available access groups again and the actions the user is authorized to do may change. The most common <auth-program> to use is ckpasswd, which supports several ways of checking passwords including using PAM. See the ckpasswd(8) man page for more details.

When matching auth groups, the last auth group in the file that matches a given connection and username/password combination is used.

An access group definition usually looks like:

```
    access <name> {
        users: <identity-wildmat>
        newsgroups: <group-wildmat>
        # ...possibly other settings
    }
```

Again, <name> is just for documentation purposes. This says that all users whose identity matches <identity-wildmat> can read and post to all newsgroups matching <group-wildmat> (as before, comma-separated wildmat expressions are allowed, but "@" is not supported). Alternately, you can use the form:

```
    access <name> {
        users: <identity-wildmat>
        read: <read-wildmat>
        post: <post-wildmat>
    }
```

and matching users will be able to read any group that matches <read-wildmat> and post to any group that matches <post-wildmat>. You can also set several other things in the access group as well as override various inn.conf(5) parameters for just a particular group of users.

Just like with auth groups, when matching access groups the last matching one in the file is used to determine the user's permissions. There is an exception to this rule: if the auth group which matched the client contains a perl_access or python_access parameter, then the script given as argument is used to dynamically generate an access group. This new access group is then used to determine the access rights of the client; the access groups in the file are ignored.

There is one additional special case to be aware of. When forming particularly complex authentication and authorization rules, it is sometimes useful for the identities provided by a given auth group to only apply to particular access groups; in other words, rather than checking the identity against the users parameter of every access group, it's checked against the users parameter of only some specific access groups. This is done with the key parameter. For example:

```
    auth example {
        key: special
        hosts: *.example.com
        default: <SPECIAL>
    }
    access example {
        key: special
        users: <SPECIAL>
        newsgroups: *
        addcanlockuser: none
    }
```

In this case, the two key parameters bind this auth group with this access group. For any incoming connection matching "*.example.com" (assuming there isn't any later auth group that also matches such hosts), no access group that doesn't have "key: special" will even be considered. Similarly, the above access group will only be checked if the user was authenticated with an auth group containing "key: special". This mechanism normally isn't useful; there is almost always a better way to achieve the same result.

Also note in the example that there's no default-domain parameter, which means that no domain is appended to the default username and the identity for such connections is just "<SPECIAL>". Note that some additional add-ons to INN may prefer that authenticated identities always return a full e-mail address (including a domain), so you may want to set up your system that way if you are using add-ons. As several different persons can be assigned the same "<SPECIAL>" identity, no user-specific Cancel-Lock hashes should be generated.

Configuration files can be included in other configuration files via the syntax:

```
    include <filename>
```

The file named <filename> is then included. This syntax is allowed only at top-level.

Below is the full list of allowable parameters for auth groups and access groups, and after that are some examples that may make this somewhat clearer.

## AUTH GROUP PARAMETERS
An auth group without at least one of the res, auth, perl_auth, python_auth, or default parameters makes no sense (and in practice will just be ignored).

auth

A simple command line for a user authenticator (shell metacharacters are not supported). If a full path is not given, the program executed must be located in the pathbin/auth/passwd directory. An authenticator is a program used to handle a user-supplied username and password, via a mechanism such as AUTHINFO USER/PASS. Like with res, one auth group can have multiple auth parameters; they will be tried in order and the results of the first successful one will be used. See also perl_auth. The most common authenticator to use is ckpasswd(8); see its man page for more information.

default

The default username for connections matching this auth group. This is the username assigned to the user at connection time if all resolvers fail or if there are no res parameters. Note that it can be either a bare username, in which case default-domain (if present) is appended after an "@", or a full identity string containing an "@", in which case it will be used verbatim.

default-domain

The default domain string for this auth group. If a user resolver or authenticator doesn't provide a domain, or if the default username is used and it doesn't contain an "@", this domain is used to form the user identity. (Note that for a lot of setups, it's not really necessary for user identities to be qualified with a domain name, in which case there's no need to use this parameter.)

hosts

A comma-separated list of remote hosts, wildmat patterns matching either hostnames or IP addresses, or IP netblocks specified in CIDR notation. If a user connects from a host that doesn't match this parameter, this auth group will not match the connection and is ignored. Note that if you have a large number of patterns that can't be merged into broader patterns (such as a large number of individual systems scattered around the net that should have access), the hosts parameter may exceed the maximum line length of 8,192 characters. In that case, you'll need to break that auth group into multiple auth groups, each with a portion of the hosts listed in its hosts parameter, and each assigning the same user identity.

All hosts match if this parameter is not given.

key

If this parameter is present, any connection matching this auth group will have its privileges determined only by the subset of access groups containing a matching key parameter.

localaddress

A comma-separated list of local host or address patterns with the same syntax as the hosts parameter. If this parameter is specified, its auth group will only match connections made to a matching local interface. (Obviously, this is only useful for servers with multiple interfaces.) All local addresses match if this parameter is not given.

perl_access

A path to a Perl script for dynamically generating an access group. If an auth group matches successfully and contains a perl_access parameter, then the argument Perl script will be used to create an access group. This group will then determine the access rights of the client, overriding any access groups in readers.conf. If and only if a successful auth group contains the perl_access parameter, readers.conf access groups are ignored and the client's rights are instead determined dynamically. This parameter is only valid if INN is compiled with Perl support (--with-perl passed to "configure"). More information may be found in the file doc/hook-perl.

perl_auth

A path to a Perl script for authentication. The perl_auth parameter works exactly like auth, except that it calls the named script using the Perl hook rather than an external program. Multiple/mixed use of the auth, perl_auth, and python_auth parameters is permitted within any auth group; each line is tried in the order it appears. perl_auth has more power than auth in that it provides the authentication program with additional information about the client and the ability to return an error string and a username. This parameter is only valid if INN is compiled with Perl support (--with-perl passed to "configure"). More information may be found in doc/hook-perl.

python_access

A Python script for dynamically generating an access group. If an auth group matches successfully and contains a python_access parameter, then the argument script (without its ".py" extension) will be used to create an access group. This group will then determine the access rights of the client, overriding any access groups in readers.conf. If and only if a successful auth group contains the python_access parameter, readers.conf access groups are ignored and the client's rights are instead determined dynamically. This parameter is only valid if INN is compiled with Python support (--with-python passed to "configure"). More information may be found in the file doc/hook-python.

python_auth

A Python script for authentication. The python_auth parameter works exactly like auth, except that it calls the named script (without its ".py" extension) using the Python hook rather than an external program. Multiple/mixed use of the auth, perl_auth, and python_auth parameters is permitted within any auth group; each line is tried in the order it appears. python_auth has more power than auth in that it provides the authentication program with additional information about the client and the ability to return an error string and a username. This parameter is only valid if INN is compiled with Python support (--with-python passed to "configure"). More information may be found in doc/hook-python.

python_dynamic

A Python script for applying access control dynamically on a per newsgroup basis. If an auth group matches successfully and contains a python_dynamic parameter, then the argument script (without its ".py" extension) will be used to determine the clients rights each time the user attempts to view a newsgroup, or read or post an article. Access rights as determined by python_dynamic override the values of access group parameters such as newsgroups, read and post. This parameter is only valid if INN is compiled with Python support (--with-python passed to "configure"). More information may be found in the file doc/hook-python.

require_encryption

If set to true, an incoming connection only matches this auth group if it is encrypted, either from the beginning if the -S flag was passed to nnrpd, or after a successful use of STARTTLS, or after a successful authentication using an SASL mechanism which negotiates an encrypted layer. This parameter is only valid if INN is compiled with TLS/SSL or SASL support (by default if the OpenSSL SSL and crypto libraries or the Cyrus SASL library are found at configure time, otherwise see the --with-openssl and --with-sasl flags passed to "configure").

res

A simple command line for a user resolver (shell metacharacters are not supported). If a full path is not given, the program executed must be in the pathbin/auth/resolv directory. A resolver is an authentication program which attempts to figure out the identity of the connecting user using nothing but the connection information (in other words, the user has not provided a username and password). An example of a resolver would be a program that assigns an identity from an ident callback or from the user's hostname. One auth group can have multiple res parameters, and they will be tried in the order they're listed. The results of the first successful one will be used.

Alternatively, a res block can be used instead of a res parameter. The recognized parameters in such res blocks are:

log

A string to log in pathlog/news.notice (with "res also-log:" prepended) before the resolver is tried. One res group can have multiple log parameters, and they will be logged in the order they're listed.

program

This parameter is mandatory in a res block. Its meaning is the same as the res parameter used directly in an auth block.

```
    auth <auth-name> {
        res: <res-program>
    }

```

is therefore equivalent to:

```
    auth <auth-name> {
        res <res-name> {
            program: <res-program>
        }
    }

```

## ACCESS GROUP PARAMETERS
access

A set of letters specifying the permissions granted to the client. The letters are chosen from the following set:

A

The client may post articles with Approved header fields (in other words, may approve articles for moderated newsgroups). By default, this is not allowed.

I

The client may inject articles with IHAVE. Note that in order to inject articles with the IHAVE command, the user must also have POST permission (the "P" option). Articles injected with IHAVE are treated as though they were injected with POST, that is to say such articles must not have been previously injected (they must not contain header fields like Injection-Info).

L

The client may post to newsgroups that are set to disallow local posting (status fields "j", "n" and "x" in the active(5) file).

N

The client may use the NEWNEWS command, overriding the global setting.

P

The client may post articles.

R

The client may read articles.

Note that if this parameter is given, allownewnews in inn.conf is ignored for connections matching this access group and the ability of the client to use NEWNEWS is entirely determined by the presence of "N" in the access string. If you want to support NEWNEWS, make sure to include "N" in the access string when you use this parameter.

Note that if this parameter is given and "R" isn't present in the access string, the client cannot read regardless of newsgroups or read parameters. Similarly, if this parameter is given and "P" isn't present, the client cannot post. This use of access is deprecated and confusing; it's strongly recommended that if the access parameter is used, "R" and "P" always be included in the access string and newsgroups, read, and post be used to control access. (To grant read access but no posting access, one can have just a read parameter and no post parameter.)

addcanlockuser

If set to "none", posts made by these users will not have a user-specific hash in the Cancel-Lock header field (only the admin hash will be generated). No Cancel-Key header field will be present in cancel or supersede requests. This is a string value and the default is "username", that is to say a user-specific hash based on the identity assigned to the connection is used. Another possible value to this parameter is "ip", in which case a user-specific hash based on the IP of the connection is used (which should be a static IP so as to actually identify users).

See inn-secrets.conf(5) for more information about Cancel-Lock. The main reason for this parameter is to deactivate this authentication mechanism when the same identity or IP can be assigned by an access group to different people. Otherwise, any of these people would be able to send an authenticated withdrawal of an article originally sent by another person with the same identity or IP.

domain

When set, the value of this parameter is used for the domain part (the right-hand side after "@") of autogenerated Message-IDs, as well as for the server name indicated in Injection-Info header fields. By default, the value of this parameter is inherited from the eponym parameter in inn.conf. However, if domain is not explicitly set in readers.conf, the specific behaviour described above won't be triggered unless virtualhost is set to true.

You may also want to set the fromhost parameter (inherited from inn.conf) for the complaints address in the Injection-Info header field, if its default value should be changed, and the complaints parameter is not already set or newsmaster does not already contain an "@".

groupexactcount

This parameter controls the threshold below with nnrpd should give the exact number of still existing articles present in newsgroups instead of an estimate. The exact number is usually updated once a day during the expiry process by expirover (run by news.daily), and is updated when new articles arrive but not necessarily when articles are cancelled or overwritten in self-expiring storage methods like CNFS. When the estimated count of articles is strictly smaller than groupexactcount, nnrpd will recount the number of still existing articles, and report the exact value. If groupexactcount is set to 0, nnrpd will always recount. If set to 1, it will never recount.

Though exact article counts are not required, they may be useful to distinguish empty newsgroups by reporting an exact count of 0 instead of an estimate of 1 (when it happens, the news client may show that 1 article is present in the newsgroup, then it tries to retrieve the article, and finally does not show anything to the user).

It is not recommended to set a high value to this parameter because it will slow the responses to news clients (recounting existing articles takes time, especially on newsgroups with a lot of articles).

This is an integer value, and the default is 5.

key

If this parameter is present, this access group is only considered when finding privileges for users matching auth groups with this same key parameter.

localtime

If a Date or an Injection-Date header field is not included in a posted article, nnrpd normally adds these header fields in UTC. If this is set to true, the Date header field will be formatted in local time instead. (The Injection-Date header field is added according to the behaviour of the addinjectiondate parameter in inn.conf, and will remain in UTC, though.) This is a boolean value and the default is false. This parameter permits handling a relatively unusual corner case. It is mostly a tool for people who want to disclose their local time zone (it can be useful information in certain types of discussions), but whose clients don't for some reason, and who can arrange for the server to be in the same time zone as the client.

max_rate

If this parameter is present (and non-zero), it is used for nnrpd's rate-limiting code. The client will only be able to download at this speed (in bytes/second). Note that if an encryption layer is being used, limiting is applied to the pre-encryption datastream.

newsgroups

Users that match this access group are allowed to read and post to all newsgroups matching this comma-separated list of wildmat patterns. The empty string is equivalent to "newsgroups: *"; if this parameter is missing, the connection will be rejected (unless read and/or post are used instead).

newsmaster

Used as the contact address in the help message returned by nnrpd(8), if the virtualhost: parameter is set to true.

perlfilter

If set to false, posts made by these users do not pass through the Perl filter even if it is otherwise enabled. This is a boolean value and the default is true.

post

Like the newsgroups parameter, but the client is only given permission to post to the matching newsgroups. This parameter is often used with read to define the patterns for reading and posting separately (usually to give the user permission to read more newsgroups than they're permitted to post to). It cannot be used in the same access group with a newsgroups parameter.

pythonfilter

If set to false, posts made by these users do not pass through the Python filter even if it is otherwise enabled. This is a boolean value and the default is true. This parameter currently has no effect as Python filtering is not implemented yet in nnrpd. If you want to do Python filtering, you have to use the one implemented in innd.

read

Like the newsgroups parameter, but the client is only given permission to read the matching newsgroups. This parameter is often used with post to specify some read-only groups; it cannot be used in the same access group with a newsgroups parameter. (If read is used and post is missing, the client will have only read-only access.)

reject_with

If this parameter is present, a client matching this block will be disconnected with a "Permission denied" message containing the contents (a "reason" string) of this parameter. Some newsreaders will then display the reason to the user.

strippath

If set to true, any Path header field provided by a user in a post is stripped rather than used as the beginning of the Path header field body of the article. This is a boolean value and the default is false.

users

The privileges given by this access group apply to any user identity which matches this comma-separated list of wildmat patterns. If this parameter isn't given, the access group applies to all users (and is essentially equivalent to "users: *").

virtualhost

Set this parameter to true in order to make nnrpd behave as if it is running on a server with a different name than it actually has. The domain parameter must then be set, either in inn.conf or in the same access group. All articles and overview data displayed to clients will have their Xref header field bodies altered to appear to be from the server named in domain, and posted articles will use that server name in the Message-ID and Injection-Info header field bodies. (Moreover, if the -I flag was given to nnrpd, posting agents will be proposed to use Message-IDs containing the string specified with -I.) Similarly, the Path header field bodies displayed to clients or generated in posted articles will use the value of domain (if pathhost is not set in the access group, or has the same value as in inn.conf) or pathhost (if pathhost is set in the access group to something different than is set in inn.conf).

Also, the domain part (the right-hand side after "@") of the newsmaster e-mail mentioned in the help message returned by nnrpd will use the value of domain if the newsmaster parameter does not already have a domain part.

At least one of the domain or pathhost parameters must be set in the access group to something different than in inn.conf, otherwise nnrpd will fail to start.

Note that setting this parameter requires the server modify all posts before presenting them to the client and therefore may decrease performance slightly.

In addition, all of the following parameters are valid in access groups and override the global setting in inn.conf. See inn.conf(5) for the descriptions of these parameters:

```
    addinjectiondate, addinjectionpostingaccount,
    addinjectionpostinghost, backoff_auth, backoff_db, backoff_k,
    backoff_postfast, backoff_postslow, backoff_trigger,
    checkincludedtext, clienttimeout, complaints, fromhost,
    localmaxartsize, moderatormailer, nnrpdauthsender, nnrpdcheckart,
    nnrpdoverstats, nnrpdposthost, nnrpdpostport, organization,
    pathhost, readertrack, spoolfirst, strippostcc.
```

## SUMMARY
Here's a basic summary of what happens when a client connects:

- All auth groups are scanned and the ones that don't match the client (due to hosts, localaddress, require_encryption, etc.) are eliminated.

- The remaining auth groups are scanned from the last to the first, and an attempt is made to apply it to the current connection. This means running res programs, if any, and otherwise applying default. The first auth group (starting from the bottom) to return a valid user is kept as the active auth group.

- If no auth groups yield a valid user (none have default parameters or successful res programs) but some of the auth groups have auth lines (indicating a possibility that the user can authenticate and then obtain permissions), the connection is considered to have no valid auth group (which means that the access groups are ignored completely) but the connection isn't closed. Instead, a 480 response code (meaning that authentication is required) is returned for everything until the user authenticates.

- When the user authenticates, the auth groups are rescanned, and only the matching ones which contain at least one auth, perl_auth, or python_auth line are considered. These auth groups are scanned from the last to the first, running auth programs and perl_auth or python_auth scripts. The first auth group (starting from the bottom) to return a valid user is kept as the active auth group.

- Regardless of how an auth group is established, as soon as one is, that auth group is used to assign a user identity by taking the result of the successful res, auth, perl_auth, or python_auth line (or the default if necessary), and appending default-domain if necessary. (If the perl_access or python_access parameter is present.)

- Finally, an access group is selected by scanning the access groups from bottom up and finding the first match. (If the established auth group contained a perl_access or python_access line, the dynamically generated access group returned by the script is used instead.) User permissions are granted based on the established access group.

## EXAMPLES
Probably the simplest useful example of a complete readers.conf, this gives permissions to read and post to all groups to any connections from the "example.com" domain, except for Bob's machine, and no privileges for anyone connecting elsewhere:

```
    auth example.com {
        hosts: "*.example.com, example.com, !bob.example.com"
        default: "<EXAMPLE>"
    }
    access full {
        users: "<EXAMPLE>"
        newsgroups: *
        addcanlockuser: none
    }
```

Note that the above access realm could also be written without the users key, in which case it applies to any user identity (though in this example, the user identity that will be assigned to all matching connections is "<EXAMPLE>"). It is however recommended to keep an explicit users key so as to better view to whom the access block applies.

As the only available auth realm only matches hosts in the "example.com" domain, any connections from other hosts will be rejected immediately.

If you have some systems that should only have read-only access to the server, you can modify the example above slightly by adding an additional auth and access group:

```
    auth lab {
        hosts: "*.lab.example.com"
        default: <LAB>
    }
    access lab {
        users: <LAB>
        read: *
    }
```

If those are put in the file after the above example, they'll take precedence (because they're later in the file) for any user coming from a machine in the lab.example.com domain, everyone will only have read access, not posting access.

Here's a similar example for a news server that accepts connections from anywhere but requires the user to specify a username and password. The username and password are first checked against an external database of usernames and passwords, and then make use of PAM:

```
    auth all {
        auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
        auth: ckpasswd
    }
    access full {
        users: *
        newsgroups: *
    }
```

When the user first connects, there are no res keys and no default, so they don't receive any valid identity and the connection won't match any access groups (even ones with "users: *"). Such users receive nothing but authentication-required responses from nnrpd until they authenticate.

If they then later authenticate, the username and password are checked first by running ckpasswd with the -f option for an external file of encrypted passwords, and then uses PAM (if INN was built with PAM support) to check the password (and if that fails, it tries to check the password against the password field returned by getpwnam(3)). If both of those fail, the user will continue to have no identity; otherwise, an identity will be assigned (usually the supplied username, perhaps with a domain appended, although an authenticator technically can provide a completely different username for the identity), and the access group will match, giving full access.

It may be educational to consider how to combine the above examples; general groups always go first. The order of the auth groups actually doesn't matter, since the "hosts: example.com" one only matches connections before username/password is sent, and the "auth: ckpasswd" one only matches after; order would matter if either group applied to both cases. The order of the access groups in this case does matter, provided the newsgroups lines differ; the access group with no users line needs to be first, with the "users: <LOCAL>" group after.

Here's an example of another common case: a server that only allows connections from a local domain and has an additional hierarchy that's password-restricted.

```
    auth "example.com" {
        hosts: "*.example.com"
        auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
        default: "anonymous"
    }
    access regular {
        newsgroups: "*,!example.restricted.*"
        addcanlockuser: none
    }
    access full {
        users: "*,!anonymous"
        newsgroups: *
    }
```

In this example, unauthenticated users get the identity "anonymous", which matches only the first access group and hence doesn't get access to the "example.restricted.*" hierarchy. No user-specific Cancel-Lock elements should be generated for anonymous users. Anyone who authenticates using a password in the newsusers file gets full access to all groups. However, note that the only authentication block is limited to hostnames in the example.com domain; connections outside of that domain will never be allowed access nor have an opportunity to authenticate.

Here's a very complicated example. This is for an organization that has an internal hierarchy "example.*" only available to local shell users, who are on machines where identd(8) can be trusted. Dialup users must provide a username and password, which is then checked against RADIUS. Remote users have to use a username and password that's checked against a database on the news server. Finally, the admin staff (users "joe" and "jane") can post anywhere (including the "example.admin.*" groups that are read-only for everyone else), and are exempted from the Perl filter. For an additional twist, posts from dialup users have their Sender header field replaced by their authenticated identity.

Since this organization has some internal moderated newsgroups, the admin staff can also post messages with Approved header fields, but other users cannot.

```
    auth default {
        auth: "ckpasswd -f <pathdb in inn.conf>/newsusers"
        default: <FAIL>
        default-domain: example.com
    }
    auth shell {
        hosts: *.shell.example.com
        res: ident
        auth: ckpasswd
        default: <FAIL>
        default-domain: shell.example.com
    }
    auth dialup {
        hosts: *.dialup.example.com
        auth: radius
        default: <FAIL>
        default-domain: dialup.example.com
    }
    access shell {
        users: *@shell.example.com
        read: *
        post: "*, !example.admin.*"
    }
    access dialup {
        users: *@dialup.example.com
        newsgroups: *,!example.*
        nnrpdauthsender: true
    }
    access other {
        users: "*@example.com, !<FAIL>@example.com"
        newsgroups: *,!example.*
    }
    access fail {
        users: "<FAIL>@*"
        newsgroups: !*
    }
    access admin {
        users: "joe@*,jane@*"
        newsgroups: *
        access: "RPA"
        perlfilter: false
    }
```

Note the use of different domains to separate dialup from shell users easily. Another way to do that would be with key parameters, but this way provides slightly more intuitive identity strings. Note also that the fail access group catches not only failing connections from external users but also failed authentication of shell and dialup users before they've authenticated. The identity string given for, say, dialup users before RADIUS authentication has been attempted matches both the dialup access group and the fail access group, since it's "<FAIL>@dialup.example.com", but the fail group is last, so it takes precedence.

The shell auth group has an auth parameter so that users "joe" and "jane" can, if they choose, use username and password authentication to gain their special privileges even if they're logged on as a different user on the shell machines (or if ident isn't working). When they first connect, they'd have the default access for that user, but they could then authenticate in order to get their extended access.

Also note that if the users "joe" and "jane" are using their own accounts, they get their special privileges regardless of how they connect, whether the dialups, the shell machines, or even externally with a username and password.

Finally, here's a very simple example of a configuration for a public server for a particular hierarchy.

```
    auth default {
        hosts: *
        default: <PUBLIC>
    }
    access default {
        users: <PUBLIC>
        newsgroups: example.*
        addcanlockuser: none
    }
```

Notice that clients aren't allowed to read any other groups; this keeps them from getting access to administrative groups or reading control messages, just as a precaution. When running a public server like this, be aware that many public hierarchies will later be pulled down and reinjected into the main Usenet, so it's highly recommended that you also run a Perl or Python filter to reject any messages crossposted out of your local hierarchy, and any messages containing a Supersedes header field. This will keep messages posted to your public hierarchy from hurting any of the rest of Usenet if they leak out.

## SECURITY CONSIDERATIONS
In general, separate passwords should be used for NNTP wherever possible; the NNTP protocol itself does not protect passwords from casual interception, and many implementations (including this one) do not "lock out" accounts or otherwise discourage password-guessing attacks. So it is best to ensure that a compromised password has minimal effects.

Authentication using the AUTHINFO USER/PASS commands passes unencrypted over the network. Extreme caution should therefore be used especially with system passwords (e.g. "auth: ckpasswd -s"). Passwords can be protected by using NNTP over TLS/SSL or through ssh tunnels, and this usage can be enforced by a well-considered server configuration that only permits certain auth groups to be applied in certain cases. One can also authenticate using a strong SASL mechanism. Here are some ideas:

- To restrict connections on the standard NNTP port (119) to use an encryption layer for some (or all) of the auth groups to match, use the require_encryption parameter. Note that a client can use STARTTLS to negotiate an encrypted TLS connection. A secure layer can also be negotiated during authentication via AUTHINFO SASL.

- If you consider your local network (but not the internet) secure, have some auth groups with a restrictive hosts parameter; they would go above, with ones having global applicability below.

- Consider running nnrpd with the -S flag (either also with -D, or out of "super-server" like inetd) on the NNTPS port (563) for clients that support TLS/SSL. See nnrpd(8) for more details about how to configure that. You can use the require_encryption parameter or the -c flag to specify an alternate readers.conf file if you want a substantially different configuration for this case.

- If you want to restrict an auth group to only match loopback connections (for users running newsreaders on localhost or connecting via an ssh tunnel), use the localaddress parameter.

## HISTORY
Written by Aidan Cully <aidan@panix.com> for InterNetNews. Substantially expanded by Russ Allbery <eagle@eyrie.org>.

## SEE ALSO
auth_krb5(8), ckpasswd(8), inn.conf(5), innd(8), inn-secrets.conf(5), libinn_uwildmat(3), newsfeeds(5), nnrpd(8).


storage.conf

title: storage.conf(5)

summary: Configuration file for storage manager

text:
# storage.conf(5)

## NAME
storage.conf - Configuration file for storage manager

## DESCRIPTION
The file pathetc/storage.conf contains the rules to be used in assigning articles to different storage methods. These rules determine where incoming articles will be stored.

The storage manager is a unified interface between INN and a variety of different storage methods, allowing the news administrator to choose between different storage methods with different trade-offs (or even use several at the same time for different newsgroups, or articles of different sizes). The rest of INN need not care what type of storage method was used for a given article; the storage manager will figure this out automatically when that article is retrieved via the storage API. Note that you may also want to see the options provided in inn.conf(5) regarding article storage.

The storage.conf file consists of a series of storage method entries. Blank lines and lines beginning with a number sign ("#") are ignored. The maximum number of characters in each line is 255. The order of entries in this file is important, see below.

Each entry specifies a storage method and a set of rules. Articles which match all of the rules of a storage method entry will be stored using that storage method; if an article matches multiple storage method entries, the first one will be used. Each entry is formatted as follows:

```
    method <methodname> {
        newsgroups: <wildmat>
        class: <storage_class>
        size: <minsize>[,<maxsize>]
        expires: <mintime>[,<maxtime>]
        options: <options>
        exactmatch: <bool>
        filtered: <bool>
        path: <wildmat>
    }
```

If spaces or tabs are included in a value, that value must be enclosed in double quotes (""). If either a number sign ("#") or a double quote are meant to be included verbatim in a value, they should be escaped with "\".

<methodname> is the name of a storage method to use for articles which match the rules of this entry. The currently available storage methods are:

```
    cnfs
    timecaf
    timehash
    tradspool
    trash
```

See the "STORAGE METHODS" section below for more details.

The meanings of the keys in each storage method entry are as follows:

newsgroups: <wildmat>

What newsgroups are stored using this storage method. <wildmat> is a uwildmat pattern which is matched against the newsgroups an article is posted to. If storeonxref in inn.conf is true, this pattern will be matched against the newsgroup names in the Xref header field body; otherwise, it will be matched against the newsgroup names in the Newsgroups header field body (see inn.conf(5) for discussion of the differences between these possibilities). Poison wildmat expressions (expressions starting with "@") are allowed and can be used to exclude certain group patterns: articles crossposted to poisoned newsgroups will not be stored using this storage method. The <wildmat> pattern is matched in order. There is no default newsgroups pattern; if an entry should match all newsgroups, use an explicit "newsgroups: *".

class: <storage_class>

An identifier for this storage method entry. <storage_class> should be a number between 0 and 255. It should be unique across all of the entries in this file. It is mainly used for specifying expiration times by storage class as described in expire.ctl(5); "timehash" and "timecaf" will also set the top-level directory in which articles accepted by this storage class are stored. Storage classes can be for instance numbered sequentially in storage.conf. The assignment of a particular number to a storage class is arbitrary but permanent (since it is used in storage tokens). As a matter of fact, an article is assigned a storage class depending on the storage rules in effect at the time of its arrival. This identifier will not change even if storage.conf is modified afterwards and the same article would have been assigned another storage class, had it been received after that change. The article is still perfectly valid and retrievable. The only difference will be for expiration with groupbaseexpiry set to false in inn.conf: the rules in expire.ctl apply to the storage class assigned to articles at their arrival.

size: <minsize>[,<maxsize>]

A range of article sizes (in bytes) which should be stored using this storage method. If <maxsize> is 0 or not given, the upper size of articles is limited only by maxartsize in inn.conf. The size: field is optional and may be omitted entirely if you want articles of any size to be stored in this storage method (if, of course, these articles fulfill all the other requirements of this storage method entry). By default, <minsize> is set to 0.

expires: <mintime>[,<maxtime>]

A range of article expiration times which should be stored using this storage method. Be careful; this is less useful than it may appear at first. This is based only on the Expires header field of the article, not on any local expiration policies or anything in expire.ctl! If <mintime> is non-zero, then this entry will not match any article without an Expires header field. This key is therefore only really useful for assigning articles with requested longer expire times to a separate storage method. Articles only match if the time until expiration (that is to say, the amount of time into the future that the Expires header field of the article requests that it remain around) falls in the interval specified by <mintime> and <maxtime>. The format of these parameters is "0d0h0m0s" (days, hours, minutes, and seconds into the future). If <maxtime> is "0s" or is not specified, there is no upper bound on expire times falling into this entry (note that this key has no effect on when the article will actually be expired, but only on whether or not the article will be stored using this storage method). This field is also optional and may be omitted entirely if you do not want to store articles according to their Expires header field, if any.

A <mintime> value greater than "0s" implies that this storage method won't match any article without an Expires header field.

options: <options>

This key is for passing special options to storage methods that require them (currently only "cnfs"). See the "STORAGE METHODS" section below for a description of its use.

exactmatch: <bool>

If this key is set to true, all the newsgroups in the Newsgroups header field body (or Xref if storeonxref in inn.conf is true) of incoming articles will be examined to see if they match newsgroups patterns. (Normally, any non-zero number of matching newsgroups is sufficient, provided no newsgroup matches a poison wildmat as described above.) This is a boolean value; "true", "yes" and "on" are usable to enable this key. The case of these values is not significant. The default is false.

filtered: <bool>

If this key is set to true, the article must have been rejected by any enabled article filters (Perl or Python) for innd. This also requires that dontrejectfiltered is set to true in inn.conf. Filtered articles are usually stored in a small CNFS buffer, or another storage method with a rather tight expiration policy. This is a boolean value; "true", "yes" and "on" are usable to enable this key. The case of these values is not significant. The default is false. If all the storage classes have this key set to false, filtered articles are stored in the same storage class as accepted articles. It is only when at least one storage class has this key set to true than filtered articles and accepted articles are no longer stored mixed together in any storage class.

path: <wildmat>

What articles by their Path header field are stored using this storage method. <wildmat> is a uwildmat pattern which is matched against the Path header field body of articles, which corresponds to where articles have passed, or were posted at. Poison wildmat expressions (expressions starting with "@") are allowed and can be used to exclude certain path patterns (in lieu of expressions starting with "!" that are not considered negated because "!" has a special meaning in Path header fields). The <wildmat> pattern is matched in order. A typical use case might be to store articles from a spammy site in a small CNFS buffer to avoid overall retention impacts:

```
    path: "*!spam-site.example.com!not-for-mail"

```

The default is to match all articles.

If an article matches all of the constraints of an entry, it is stored via that storage method and is associated with that <storage_class>. This file is scanned in order and the first matching entry is used to store the article.

If an article does not match any entry, either by being posted to a newsgroup which does not match any of the <wildmat> patterns or by being outside the size and expires ranges of all entries whose newsgroups pattern it does match, the article is not stored and is rejected by innd. When this happens, the error message:

```
    cant store article: no matching entry in storage.conf
```

is logged to syslog. If you want to silently drop articles matching certain newsgroup patterns or size or expires ranges, assign them to the "trash" storage method rather than having them not match any storage method entry.

## STORAGE METHODS
Currently, there are five storage methods available. Each method has its pros and cons; you can choose any mixture of them as is suitable for your environment. Note that each method has an attribute EXPENSIVESTAT which indicates whether checking the existence of an article is expensive or not. This is used to run expireover(8).

cnfs

The "cnfs" storage method stores articles in large cyclic buffers (CNFS stands for Cyclic News File System). Articles are stored in CNFS buffers in arrival order, and when the buffer fills, it wraps around to the beginning and stores new articles over the top of the oldest articles in the buffer. The expire time of articles stored in CNFS buffers is therefore entirely determined by how long it takes the buffer to wrap around, which depends on how quickly data is being stored in it. (This method is therefore said to have self-expire functionality. It also means that when an article is cancelled, the cycbuff doesn't go back and use space until it rolls over and the whole cycbuff starts being reused.) EXPENSIVESTAT is false for this method. CNFS has its own configuration file, cycbuff.conf, which describes some subtleties to the basic description given above. Storage method entries for the "cnfs" storage method must have an options: field specifying the metacycbuff into which articles matching that entry should be stored; see cycbuff.conf(5) for details on metacycbuffs.

Advantages: By far the fastest of all storage methods (except for "trash"), since it eliminates the overhead of dealing with a file system and creating new files. Unlike all other storage methods, it does not require manual article expiration. With CNFS, the server will never throttle itself due to a full spool disk, and groups are restricted to just the buffer files given so that they can never use more than the amount of disk space allocated to them.

Disadvantages: Article retention times are more difficult to control because old articles are overwritten automatically. Attacks on Usenet, such as flooding or massive amounts of spam, can result in wanted articles expiring much faster than intended (with no warning).

timecaf

This method stores multiple articles in one file, whose name is based on the article's arrival time and the storage class. The file name will be:

```
    <patharticles>/timecaf-nn/bb/aacc.CF

```

where "nn" is the hexadecimal value of <storage_class>, "bb" and "aacc" are the hexadecimal components of the arrival time, and "CF" is a hardcoded extension. (The arrival time, in seconds since the epoch, is converted to hexadecimal and interpreted as 0xaabbccdd, with "aa", "bb", and "cc" used to build the path.) This method does not have self-expire functionality (meaning expire has to run periodically to delete old articles, as well as cancelled articles if immediatecancel is not set to true in inn.conf). EXPENSIVESTAT is false for this method.

A given CAF file contains all the articles received during a time frame of 4 minutes or so (256 seconds), and is limited to 262,144 articles and about 3,5 GB. It is enough for normal operations. The only caveat is when you're feeding at high speed bunches of articles between two servers; you'll then want to limit it to that amount of articles during the time frame when a CAF file stores newly arrived articles.

Advantages: It is roughly four times faster than "timehash" for article writes, since much of the file system overhead is bypassed, while still retaining the same fine control over article retention time.

Disadvantages: Using this method means giving up all but the most careful manually fiddling with the article spool; in this aspect, it looks like "cnfs". As one of the newer and least widely used storage types, "timecaf" has not been as thoroughly tested as the other methods.

timehash

This method is very similar to "timecaf" except that each article is stored in a separate file. The name of the file for a given article will be:

```
    <patharticles>/time-nn/bb/cc/yyyy-aadd

```

where "nn" is the hexadecimal value of <storage_class>, "yyyy" is a hexadecimal sequence number, and "bb", "cc", and "aadd" are components of the arrival time in hexadecimal (the arrival time is interpreted as documented above under "timecaf"). This method does not have self-expire functionality. Cancelled articles are removed immediately. EXPENSIVESTAT is true for this method.

Advantages: Heavy traffic groups do not cause bottlenecks, and a fine control of article retention time is still possible.

Disadvantages: The ability to easily find all articles in a given newsgroup and manually fiddle with the article spool is lost, and INN still suffers from speed degradation due to file system overhead (creating and deleting individual files is a slow operation).

tradspool

Traditional spool, or "tradspool", is the traditional news article storage format. Each article is stored in an individual text file named:

```
    <patharticles>/news/group/name/nnnnn

```

where "news/group/name" is the name of the newsgroup to which the article was posted with each period changed to a slash, and "nnnnn" is the sequence number of the article in that newsgroup. For crossposted articles, the article is linked into each newsgroup to which it is crossposted (using either hard or symbolic links). This is the way versions of INN prior to 2.0 stored all articles, as well as being the article storage format used by C News and earlier news systems. This method does not have self-expire functionality. Cancelled articles are removed immediately. EXPENSIVESTAT is true for this method.

Advantages: It is widely used and well-understood; it can read article spools written by older versions of INN and it is compatible with all third-party INN add-ons. This storage mechanism provides easy and direct access to the articles stored on the server, makes writing programs that fiddle with the news spool very easy, gives fine control over article retention times, and comes with the scanspool support utility to perform sanity checks.

Disadvantages: It takes a very fast file system and I/O system to keep up with current Usenet traffic volumes due to file system overhead. Groups with heavy traffic tend to create a bottleneck because of inefficiencies in storing large numbers of article files in a single directory. It requires a nightly expire program to delete old articles out of the news spool, a process that can slow down the server for several hours or more.

trash

This method silently discards all articles stored in it. Its only real uses are for testing and for silently discarding articles matching a particular storage method entry (for whatever reason). Articles stored in this method take up no disk space and can never be retrieved, so this method has self-expire functionality of a sort. EXPENSIVESTAT is false for this method.

## EXAMPLES
The following sample storage.conf file would store all articles posted to alt.binaries.* in the "BINARIES" CNFS metacycbuff, all articles over roughly 50 KB in any other hierarchy in the "LARGE" CNFS metacycbuff, all other articles in alt.* in one timehash class, and all other articles in any newsgroups in a second timehash class, except for the internal.* hierarchy which is stored in traditional spool format.

```
    method tradspool {
        class: 1
        newsgroups: internal.*
    }
    method cnfs {
        class: 2
        newsgroups: alt.binaries.*
        options: BINARIES
    }
    method cnfs {
        class: 3
        newsgroups: *
        size: 50000
        options: LARGE
    }
    method timehash {
        class: 4
        newsgroups: alt.*
    }
    method timehash {
        class: 5
        newsgroups: *
    }
```

Notice that the last storage method entry will catch everything. This is a good habit to get into; make sure that you have at least one catch-all entry just in case something you did not expect falls through the cracks. Notice also that the special rule for the internal.* hierarchy is first, so it will catch even articles crossposted to alt.binaries.* or over 50 KB in size.

As for poison wildmat expressions, if you have for instance an article crossposted between misc.foo and misc.bar, the pattern:

```
    misc.*,!misc.bar
```

will match that article whereas the pattern:

```
    misc.*,@misc.bar
```

will not match that article. An article posted only to misc.bar will fail to match either pattern.

Usually, high-volume groups and groups whose articles do not need to be kept around very long (binaries groups, *.jobs*, news.lists.filters, etc.) are stored in CNFS buffers. Use the other methods (or CNFS buffers again) for everything else. However, it is as often as not most convenient to keep in "tradspool" special hierarchies like local hierarchies and hierarchies that should never expire or through the spool of which you need to go manually.

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

## SEE ALSO
cycbuff.conf(5), expire.ctl(5), expireover(8), inn.conf(5), innd(8), libinn_uwildmat(3), scanspool(8).


subscriptions

title: subscriptions(5)

summary: Default recommended subscriptions

text:
# subscriptions(5)

## NAME
subscriptions - Default recommended subscriptions

## DESCRIPTION
The pathetc/subscriptions file contains a list of newsgroups that is returned by the NNTP command LIST SUBSCRIPTIONS.

Clients that support this command usually send it the first time they connect to a new news server. They use the returned list to initialize the list of subscribed newsgroups. The subscriptions file therefore should contain groups intended for new users, for testing, or that contain FAQs and other useful information for first-time Usenet users.

The syntax of the subscriptions file is trivial; it is a simple list of newsgroup names, one per line. The order of newsgroups may be significant; the news reading client may present the groups in that order to the user.

Be aware that use of the LIST SUBSCRIPTIONS command is not widespread (though documented in RFC 6048) and most news clients will never ask for this file.

## EXAMPLE
A typical subscriptions file may look like:

```
    news.announce.newusers
    news.newusers.questions
    local.test
    local.general
    local.talk
    misc.test
    misc.test.moderated
    news.answers
    news.announce.newgroups
```

This gives the client the FAQs and question newsgroup for new users first, then a local newsgroup for testing and various commonly-read local discussion groups, followed by the world-wide test groups, all the FAQs, and announcements of new world-wide newsgroups. If there is a local new users group, one might want to list it first.

## HISTORY
Written by Bettina Fink <laura@hydrophil.de> for InterNetNews.

## SEE ALSO
nnrpd(8).