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. Only 5 is accepted: any other number is an error, so a file written for an older NewsCache (versions 1 to 4) is refused instead of misread. The line may be left out; if it is there, 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).
TLSListenTo address[:port]		A second listener for TLS clients (from 1.3.23), same form, default port 563; needs TLSCertFile and TLSKeyFile. See TLS for Clients.
TLSCertFile, TLSKeyFile		PEM certificate chain and key for TLS clients.
TLSPriority string	system default	GnuTLS priority string for TLS clients.
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	The host name in the Message-IDs NewsCache makes for posted articles that have none. The default is what newscache -f prints (localhost if there is none); set it if that is wrong.
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; 0 disables the command/I/O timeout). The same limit applies to each write, and plus 10 seconds to each read inside a command such as POST. A client that stops reading is disconnected after a write times out; failed buffered output is not retried through further timeouts. The TLS handshake has a separate maximum of 30 seconds, even when this is 0.
AuthFailureDelay seconds	1	Wait before answering a failed login, the same after each failure; 0 or 1 (values up to 3600 are accepted for older configs but count as 1). 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 n	0	Priority increment for the daemon (-20 to 20). The session processes (one per client) use it too: a session forked by the standalone daemon adds it once more to the priority it inherits.
NiceClient n	10	Meant for the session processes; read (-20 to 20), but it has no effect in this version.
NiceClean n	3	Priority increment for newscacheclean (-20 to 20). Up to 1.3.22, newscacheclean used NiceServer instead.
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), right after connecting (after STARTTLS with starttls) and again when the server asks with 480. newscache -p and XDEBUG print # Password set, not shown instead of the password.
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 a connection attempt, in newscache and updatenews (0 to 86400). It applies to each address of the server's name in turn (IPv6 and IPv4) and covers only the TCP connection; the greeting falls under ReadTimeout. 0 leaves it to the system, which can take minutes for a server that doesn't answer.
ConnectBackoff seconds	0	After a connection has failed (refused, timed out, or failed while it was set up: greeting, STARTTLS, login), don't try again for this long; a command that needs the server fails at once instead. Each session and each updatenews run keeps its own record. 0 to 86400; 0 tries every time.
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 disables this per-I/O timeout). NewsCache connects again (up to Retries times), or answers the client with 403. TLS handshakes and some whole replies have separate deadlines; see Upstream Servers and TLS.
Retries n	3	How often NewsCache connects again and resends the command when the connection breaks during a command: the server closes it, answers 400, or ReadTimeout runs out (0 to 100; 0 gives up at once). A 503 counts only when the server closed the connection behind it. A first connection that fails isn't retried.
Commands flags	all on	Switch off commands the server handles badly: not-over, not-listgroup.

Retries and ReadTimeout are options of a Server entry only; at the top level of the file they are an error.

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	NewsCache gives a posted article without a Message-ID one of its own (see Hostname). With dontgenmsgid, an article that goes only to this server is passed on without one, and the server makes it. An article for several servers always gets one; missing Date and Injection-Date are also added once so all copies match.

TLS details are on Upstream Servers and TLS.