Configuration

Configuration

The configuration file is ${sysconfdir}/newscache.conf, usually /etc/newscache.conf; -c file selects another one. newscache, newscacheclean and updatenews all read it. Keywords are case-sensitive. The last line counts even without a newline at its end.

Numeric options take a plain decimal number within a range (listed in newscache.conf(5) and in the tables below). Anything else, such as ClientTimeout 20m or MaxConnections ten, is a configuration error with the file and line, and the program doesn't start.

The complete reference is newscache.conf(5); etc/newscache.conf-dist is an annotated sample (installed as newscache.conf-dist). It also works as it is: copied to /etc/newscache.conf, it reads from news.blueworldhosting.com over TLS and lets no client in until you add one. Packages can install it that way. Its commented-out Server entries show news-fra.pugleaf.net and archive.usenet.blueworldhosting.com.

A minimal configuration

One upstream server over TLS, and a local network that may read and post. Everybody else is refused.

ConfigVersion 5
ServerType standalone
ListenTo DEFAULT
Username news
Groupname news
Admin root@localhost
SpoolDirectory /var/cache/newscache
SpoolSize 1000000
LogDirectory /var/log/newscache

AccessList {
  Client 192.0.2.0/24 {
    allow read post
    List *
    Read *
    PostTo *
    Authentication none
  }
  Default {
    allow none
  }
}

NewsServerList {
  Server news.blueworldhosting.com 563 {
    Read *
    PostTo *
    GroupTimeout 300
    Options ssl
  }
}

Replace 192.0.2.0/24 with your network. news.blueworldhosting.com is a free server that needs no account; for plain NNTP use port nntp (119) and leave out Options ssl. Other public servers are listed in the README.

Nothing is allowed by default, not even localhost. A client gets 502 You have no permission to talk unless an AccessList entry allows it. See Access and Authentication.

Checking and reloading

newscache -c /etc/newscache.conf -p

-p prints the configuration as NewsCache parsed it, or the line of the first error (for example /etc/newscache.conf:10: unknown keyword). Upstream passwords are not printed; each one is replaced by the comment # Password set, not shown.

A running daemon re-reads the file on SIGHUP (systemctl reload newscache). If the new file has an error, it logs it and keeps the old configuration.

Global options

Option	Default	Meaning
ConfigVersion 5		Syntax version of the file; put it first.
ServerType standalone|inetd	standalone	Run as a daemon, or from inetd (newscache -i).
ListenTo address[:port]	DEFAULT	Address to listen on (numeric; host names are not resolved). DEFAULT (or DEFAULT:port) listens on all IPv6 and IPv4 addresses with one socket (IPv4 only where the host has no IPv6); 0.0.0.0 listens on IPv4 only. IPv6 addresses as [addr]:port. The port may be a service name or a number; default nntp (119).
CachePort port		Older way to set the port: a service name, a number or #number. Ignored (with a log line) when the file has a ListenTo line, as the shipped newscache.conf-dist does; use ListenTo DEFAULT:port instead. Before 1.3.22 it didn't work at all.
Username, Groupname	none	User and group NewsCache switches to after binding the port. Without Groupname, the user's primary group. Started as root without Username, NewsCache and every session keep running as root, and the log says so with a warning. A user or group that doesn't exist is logged, and the daemon stops.
Hostname name	the host's FQDN	Only if NewsCache can't determine the host name (newscache -f shows it).
Admin address	notset	Administrator's e-mail address, shown by HELP.
PidFile file	none	Write the daemon's pid there. Removed at SIGTERM/SIGINT if the directory is writable for Username, otherwise emptied. Only a regular file with one link is written: a symbolic link or a hard link at that name is left alone, with a warning. Not needed under systemd.
MaxConnections n	32	Simultaneous clients (standalone only), 1 to 1000000; more get 400 too many users.
ClientTimeout seconds	1200	Close a client connection after this much inactivity (0 to 86400). The same limit applies to each write to the client, and (plus 10 seconds) to each read inside a command, such as the article of a POST: a client that stops reading its replies, or stops in the middle of an article, is disconnected too.
AuthFailureDelay seconds	15	Wait before answering a failed login, times the number of failed logins in the connection; 0 to 3600. After the third failure the connection is closed.
Timeouts active descriptions	3600 3600	How long the active list stays valid, in seconds (the second value is for group descriptions, which NewsCache doesn't fetch); 0 to 2147483647.
MaxArticleSize bytes	1048576	The largest article taken from an upstream server (1024 to 1073741824). A larger one is an error: the client gets 403, nothing is stored, and the connection to that server is closed. Lines outside articles (status lines, overview records, the active list) may have at most 16 KiB.
MaxPostSize bytes	1048576	The largest article a client may post (1024 to 1073741824, counted with CRLF line ends). A larger one is read to its end and refused with 441; the session goes on.
SpoolDirectory dir	/var/cache/newscache	Where the cache lives. Must be local and writable for Username.
SpoolSize kbytes	1048576	Size newscacheclean keeps the spool under, the message-ID history included. A plain number of KB; values of 1 TB and more work.
History on|off	off	Serve message-ID requests from the spool, using a history in SpoolDirectory/.history. See Caching and Large Groups.
PrefetchFile file	none	Groups (or wildmat patterns) for updatenews. See Caching and Large Groups.
LogDirectory dir	none	Log files, for builds with --without-syslog. The programs open their log before they switch to Username, so a directory only root can write is enough when they start as root. Only a regular file with one link is used: a symbolic or hard link is refused with an error on stderr, except a symbolic link to the program's own stderr (such as /dev/stderr, as in the container image).
LogStyle ...	hostname ip-address	Any of strict-inn, hostname, ip-address.
NiceServer, NiceClient, NiceClean	0, 10, 3	Priority increments for the daemon, the client processes and newscacheclean; -20 to 20. Up to 1.3.22, newscacheclean used NiceServer instead of NiceClean.
AccessList { ... }		Which clients may do what: Access and Authentication.
NewsServerList { ... }		Upstream servers: below and Upstream Servers and TLS.

NewsServerList

NewsServerList {
  Server host port {
    Read grouplist
    PostTo grouplist
    GroupTimeout seconds
    ...
  }
  NoServer {
    Read grouplist
    PostTo grouplist
  }
}

Each group is read from the server whose Read list matches it most specifically, and a posting goes to the server whose PostTo list matches its groups. If several entries match a group equally (two with Read *), the first one is used. NoServer names groups that come from no server.

Per-server options:

Option	Default	Meaning
Read list		Groups read from this server (comma-separated; * at the end of a name matches anything, ! excludes).
PostTo list		Groups posted through this server.
GroupTimeout seconds	600	How long a group's information stays valid before NewsCache asks the server again (0 to 2147483647).
User, Password		Login at the upstream server (AUTHINFO).
Options flags	cached setpostflag	See below.
TLSCAFile file	system trust store	CA certificates for this server's TLS certificate.
BindFrom address		Local address for connections to this server (numeric only).
LimitGroupSize n	0 (no limit)	Clients see only the newest n article numbers of each group (0 to 4294967295). Not needed for large groups any more.
ConnectTimeout seconds	0	Time limit for connecting to the server, in newscache and updatenews (0 to 86400). 0 leaves it to the system, which can take minutes for a server that doesn't answer.
ConnectBackoff seconds	0	After a failed connect, don't try again for this long (0 to 86400).
ReadTimeout seconds	300	Give up the connection when the server sends or accepts nothing for this long, on each read and write (0 to 86400; 0 waits for ever). NewsCache connects again (up to Retries times), or answers the client with 403.
Retries n	3	Reconnect attempts when the server closes the connection (0 to 100).

| Commands flags | all on | Switch off commands the server handles badly: not-over, not-listgroup. |

Options flags:

Flag	Meaning
cached / not-cached	Store articles from this server, or only pass them through (for example for a local news server).
offline / not-offline	Never contact this server; only what updatenews fetched is available.
semioffline	Contact the server when needed, except for the list of groups (fetch that with updatenews -a).
setpostflag / not-setpostflag	Mark groups as not postable (n) in the active list if the server doesn't allow posting.
ssl	TLS from the start of the connection (usually port 563).
starttls	Plain connection, then STARTTLS (usually port 119); never falls back to plain text.
noverify	With ssl/starttls: don't verify the server's certificate (logged as a warning).
dontgenmsgid	Don't add a Message-ID to postings without one; leave that to the server.

TLS details are on Upstream Servers and TLS.