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 complete reference is newscache.conf(5); etc/newscache.conf-dist is an annotated sample (installed as newscache.conf-dist).

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. Use ListenTo DEFAULT:port instead.
Username, Groupname	none	User and group NewsCache switches to after binding the port. Without Groupname, the user's primary group.
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. Not needed under systemd.
MaxConnections n	32	Simultaneous clients (standalone only); more get 400 too many users.
ClientTimeout seconds	1200	Close a client connection after this much inactivity.
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).
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.
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.
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.
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. 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.
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. Not needed for large groups any more.
ConnectTimeout seconds		Time limit for connecting to the server.
ConnectBackoff seconds		After a failed connect, don't try again for this long.
Retries n	3	Reconnect attempts when the server closes the connection.
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.