Administration Guide¶
Installation and initial setup¶
This manual describes the installation and setup on a Debian-based Linux system with a Postgres backend. You may have to adapt the commands to your actual setup.
Dependencies¶
The following dependencies are required:
Java 21 SDK
Maven
A database system, e.g. Postgres 17
To install the dependencies on a Debian system issue the following commands as root (or with sudo):
# apt install openjdk-21-jdk-headless maven postgresql git
Prepare system¶
It is recommended to create a restricted user account to run sonews on a port > 1024 and later redirect NNTP port 119 to the higher port.
To create a user ‘sonews’:
# useradd -m /opt/sonews sonews
# su - postgres
$ mkdir sonews
If you have an SSH server running, prevent this user from remote login, e.g. add this to /etc/ssh/sshd_config and reload the ssh daemon:
DenyUsers sonews
# systemctl reload ssh
# systemctl reload sshd
You can now switch to this user to build sonews from source.
Building from source¶
You may also checkout a recent version from Codeberg
$ git clone https://codeberg.org/chrlns/sonews.git sonews-git
$ git checkout tags/<stable-release>
Replace stable-release with an appropriate release tag, e.g. ‘sonews-2.1.0’ (see Releases or use git tag -l). You can omit the checkout step if you want to build current development version (which is the only way before 2.1 release…).
Maven will download all necessary dependencies from a repository automatically. Use the following command to build and package sonews:
$ cd sonews-git
$ mvn package
If you encounter an error related to IPv6 network connectivity, for example if you are on a system that does not have IPv4, you can force maven to use IPv6:
$ mvn -Djava.net.preferIPv6Addresses=true package
After building you will find the resulting sonews-2.1-SNAPSHOT-jar-with-dependencies.jar file in the target/ directory. The archive contains all necessary binaries. Now we can prepare the database.
Initial database setup¶
Before you start sonews, you must prepare the database. Currently sonews is known to work with PostgreSQL (preferred) and MariaDB/MySQL.
It is highly recommended to create an own database for every sonews instance, e.g. called ‘sonews’. Additionally, it is recommended to create a unique database user for sonews, e.g. ‘sonewsuser’. Do not use the (db) root user for sonews! The sonews user needs rights for SELECT, INSERT and UPDATE statements. Refer to the database manual for instructions.
You will find the SQL Schema definitions (database_*.sql) in the util/ subdirectory of the source and binary distributions.
Use these templates and a database tool (e.g. phpMyAdmin, pgAdmin, etc.) to create the necessary table structures.
Use the following commands as root for PostgreSQL to create a dedicated ‘sonews’ user and database ‘sonews’:
# sudo -u postgres createuser sonews
# sudo -u postgres createdb sonews
Then enter the psql shell to fine tune the database setup:
# sudo -u postgres psql
postgres=# ALTER USER sonews WITH ENCRYPTED PASSWORD '<yoursecretepassword>';
postgres=# GRANT ALL PRIVILEGES ON DATABASE sonews TO sonews;
Make sure you fill in the correct database settings in the sonews.conf file (see later).
Now we can create the required database tables from the template file:
# sudo -u postgres psql -d sonews < /opt/sonews/sonews-git/util/database_postgres_tables.sql
You should see some CREATE TABLE and ALTER TABLE statements on screen and no error message. There is also a template for MariaDb (which should work for MySQL as well).
Prepare working directory¶
Switch to sonews user: .. code-block:: console
# su - sonews $ ls
You now have the source code with the binary in sonews-git and a working directory for sonews. To have a clean setup we will now copy or link the necessary files to the working directory.
$ cd sonews
$ cp ../sonews-git/groups.conf.example groups.conf
$ cp ../sonews-git/peers.conf.example peers.conf
$ cp ../sonews-git/sonews.xml.example sonews.xml
$ cp ../sonews-git/util/sonews.conf.example sonews.conf
$ chmod 600 sonews.conf
$ ln -s ../sonews-git/target/sonews-2.1-jar-with-dependencies.jar sonews.jar
Edit sonews.conf according to your database settings (user, passsword, dbmsdriver, database). An explanation of all configuration values can be found in the next section. Once you adapted the config, sonews should be ready to start.
Configuration values¶
There is a bootstrap configuration in util/sonews.conf.example and a regular configuration in the database table config. If no config is provided, a default one will be created on first startup.
There are various configuration values that can be adapted:
- ‘sonews.article.maxsize’
Maximum allowed body size of a news message given in kilobytes. Please note that for MySQL the ‘max_allowed_packet’ configuration variable must be set to a value higher than ‘sonews.article.maxsize’ otherwise posting of large mails will fail.
- ‘sonews.hostname’
Canonical name of the server instance. This variable is part of the server’s hello message to the client and used to generate Message-Ids. It is recommended to set sonews.hostname to the full qualified domain name (FQDN) of the host machine otherwise default ‘localhost’ will be used.
- ‘sonews.loglevel’
Specifies the minimum log level of messages sonews is logging to the logfile. Default: INFO. Can be one of the following values: ALL, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, OFF (disables logging)
- ‘sonews.port’
Listening port of sonews daemon. This value can be overridden with the -p command line argument. Default: 9119 (the default NNTP port is 119 which requires root to run)
- ‘sonews.timeout’
Socket timeout for client connections in seconds. Default as recommended in RFC3977 is 180 seconds.
- ‘sonews.storage.database’
Database connect string in the form: protocol:subprotocol:protocolspecific
Example for PostgreSQL database sonews running on localhost: jdbc:postgresql:sonews
- ‘sonews.storage.user’
Database user name
- ‘sonews.storage.password’
Database user password
Startup from commandline¶
Start sonews directly listening on port 9119 (command line argument -p to change the port) from the prepared working directory:
$ java -jar sonews.jar
If you are on a IPv6-only system, add -Djava.net.preferIPv6Addresses=true before -jar argument.
You can also start sonews from the source tree using Maven:
$ mvn exec:java -Dexec.mainClass="org.sonews.Main" -Dexec.args="-p 9119"
Start as daemon¶
It is recommended to start sonews as daemon with proper logging. You will finde helper scripts in the util directory of the source tree. If you are on a Linux system with systemd, you can use util/sonews.service to create a service:
# cp util/sonews.service /etc/systemd/system/sonews.service
Modify /etc/systemd/system/sonews.service according to your system (paths etc.), then:
# systemctl daemon-reload
# systemctl enable sonews
# systemctl start sonews
With systemd logging you can follow the sonews log:
# journalctl -fu sonews
Port redirection¶
The default NNTP port is 119 which normally requires root to listen from. Running a service as root is definitely not recommended, so you should run sonews as normal user, listening on port 9119 (or another port > 1024) and use iptables (or the tool of your operating system) to redirect requests to port 119 to the actual listening port. On a Linux system that can be done as follows:
For IPv4
# iptables -t nat -A PREROUTING -p tcp --dport 119 -j REDIRECT --to-port 9119
For IPv6
# ip6tables -t nat -A PREROUTING -p tcp --dport 119 -j REDIRECT --to-port 9119
Make sure IP forwarding is enabled:
# echo 1 | tee /proc/sys/net/ipv6/conf/all/forwarding
# echo 1 | tee /proc/sys/net/ipv4/ip_forward
To persist changes to iptables, so that the forwarding is still active after reboot, you can use iptables-persistent on Debian-based systems:
# apt-get install iptables-persistent
# netfilter-persistent save
# netfilter-persistent reload
Newsgroup configuration¶
The newsgroups are configured in the groups.conf configuration file. A sample file is provided as groups.conf.sample:
# Groupname Flags
control 8
local.test 8
The file contains one group per file. At first the name followed by flags. The flags number indicates which properties the group has:
0: default, normal newsgroup with read/write access
1: Mailinglist, newsgroup is a mirror of an email mailinglist
2: read-only, newsgroup is readonly
4: private, newsgroup is only visible to cleints of the private clients access list
8: local, newsgroup is local to this server and not peered
128: deleted, news group is marked as deleted and sonews may remove it from the database
The flags can be combined, e.g. flag = 12 is a private local newsgroup.
Peering¶
sonews is able to synchronize selected groups with other newsservers using push or pull mechanisms.
To enable the peering feature sonews must be started with the -peering command-line argument.
The peering mechanism is configured in the peers.conf file. A sample is provided in peers.conf.sample:
# Configuration file for Usenet peering
# Format:
# [PUSH|PULL] GROUPNAME HOST
PULL news.software.servers.sonews news.sonews.org
PUSH news.software.servers.sonews news.sonews.org
To peer with a remote server in both directions you need both a PUSH and a PULL entry. The push feeder is used every time a news message is posted to the local sonews instance. The news message is then immediately pushed to the remote host. The pull feeder checks the remote host in intervals for new messages and retrieves them.