Grouping and controlling multiple Radiator instances with systemd

Introduction

Radiator Linux packages provide by default two systemd service files — /lib/systemd/system/radiator.service for single instance and /lib/systemd/system/radiator@.service for multiple instances configuration. The single instance configuration expects to find its configuration from /etc/radiator/radiator.conf while the multiple instances configuration expects each instance configuration to be named as /etc/radiator/radiator-<instance>.conf e.g. /etc/radiator/radiator-proxy.conf. When naming instances, it's better to use underscores instead of hyphens, so filenames would be like radiator-auth_internal.conf or radiator-wifiaccounting.conf.

When configuration files are in place, the instances can be enabled/disabled with following commands.

Single instance enable/disable:

systemctl enable radiator
systemctl disable radiator


Multiple instance enable/disable (instance name proxy, configuration file name radiator-proxy.conf):

systemctl enable radiator@proxy
systemctl disable radiator@proxy

All the commands above and in these instructions require root privileges, so open a root shell or use sudo to make sure that commands work.

Please note that enabling or disabling an instance does not start or stop the instance. It only controls if an enabled instance is started when starting the server. For starting and stopping instances manually there are systemctl start <instance> and systemctl stop <instance> commands e.g systemctl start radiator@proxy.

Sometimes there exists a need to run multiple Radiator hosts on a single host — for example when one has separated RADIUS proxy and authentication functionality into multiple separate instances. The reasons to do so vary from clarifying configuration to optimising performance by running multiple Radiator processes instead of a single one.

When multiple instances are used, managing and restarting them separately may become burdensome. Together with Radiator's systemd service files, systemd provides the means to group and control multiple Radiator instances with one virtual systemd service. These instructions follow the systemd configuration guidelines as described by Linux distribution manuals.

Preparations before starting

Please check and do at least the following before starting to migrate to virtual systemd service model:

1. Ensure that your Radiator instance configurations work as manually controlled services. This means that you have working configurations for them and are able to enable, disable, start and stop them without any problems. If you run into trouble getting instance configurations running, check the configuration file owner, group and file permissions so that they are readable by radiator user or group.
2. Stop and disable all Radiator instances.

These will ensure that you can more easily detect problems with the virtual systemd service configuration, when you know for sure that the instances and their configurations are already tested to be working. Stopping and disabling them ensures that you will start from clean slate when adding new virtual systemd service files.

When editing systemd service files, please do not edit and change files in /lib/systemd/system as the next Linux Radiator package upgrade will overwrite those files. The proper place to do these adjustments is under /etc/systemd/system as the following instructions will also describe.

Setting up virtual systemd service to control multiple instances

The actual implementation varies with the version of systemd, but for clarity, we have divided the instructions according to tested and compatible Linux distribution versions.

RHEL 8 / 9, Ubuntu 18.04 / 20.04 / 22.04 / 24.04 LTS, Debian 10 / 11 / 12

Configuration files

Create the virtual systemd service file /etc/systemd/system/radiator-instances.service with the following content:

[Unit]
Description=Virtual service for managing all Radiator instances

[Service]
# The dummy program will exit
Type=oneshot
# Execute a dummy program
ExecStart=/bin/true
# This service shall be considered active after start
RemainAfterExit=yes

[Install]
# Components of this application should be started at boot time
WantedBy=multi-user.target

Adjust existing radiator@.service file by creating a directory /etc/systemd/system/radiator@.service.d and creating adjustment file /etc/systemd/system/radiator@.service.d/custom.conf with the following content:

[Unit]
PartOf=radiator-instances.service

[Install]
WantedBy=radiator-instances.service

Controlling the instances

When you have finished creating the files and directory, you can enable the virtual service and instance(s) for example with the following command (assuming you have instances proxy and auth):

systemctl enable radiator-instances radiator@proxy radiator@auth

You can then control all instances either separately or by directing the virtual service radiator-instances with commands like:

systemctl start radiator-instances
systemctl stop radiator-instances
systemctl restart radiator-instances

The virtual radiator-instances now controls all radiator@.instance based instances on host. If you need more granular control, of which services are controlled radiator-instances, you need check Grouping instances to control section in the end.

Centos 7, Debian 9, RHEL 7, Ubuntu 16.04 LTS, Oracle Linux

Configuration files

Centos 7, Red Hat 7 and Ubuntu 16.04 LTS have an older version of systemd, which is not able to understand instance configuration adjustment directories like /etc/systemd/system/radiator@.service.d. Because of this, on these platforms, the radiator@.service itself needs to be copied to /etc/systemd/system directory to be adjusted. The disadvantage of this is that if new Radiator packages update the radiator@.service, the updates need to be edited manually to the /etc/systemd/system/radiator@.service file.


Create the virtual systemd service file /etc/systemd/system/radiator-instances.service with the following content:

[Unit]
Description=Virtual service for managing all Radiator instances

[Service]
# The dummy program will exit
Type=oneshot
# Execute a dummy program
ExecStart=/bin/true
# This service shall be considered active after start
RemainAfterExit=yes

[Install]
# Components of this application should be started at boot time
WantedBy=multi-user.target

Copy the /lib/systemd/system/radiator@.service file to /etc/systemd/system/radiator@.service and add the following lines to it.

To [Unit] section add line:

PartOf=radiator-instances.service

To [Install] section add line:

WantedBy=radiator-instances.service

Controlling the instances

When you have finished creating the files, you can control the instances like already presented in the RHEL 8 / 9, Ubuntu 18.04 / 20.04 / 22.04 / 24.04 LTS, Debian 10 / 11 / 12 — Controlling the instances section.

Grouping instances to control

The above instructions assume that you want to control all Radiator instances on a host with the radiator-instances service, but if you want to select the instances the control, the recommended way is to create renamed radiator-instances and radiator@.service under /etc/systemd/system. This approach is common for all mentioned Linux distributions and Radiator packages

For example if you wanted to group certain organisation's instances on host under a virtual service, you could create radiator-organisation-instances.service and copy /lib/systemd/system/radiator@.service as radiator-organisation@.service under /etc/systemd/system. In this case it does not matter if you use newer or older systemd as it is better to separate radiator-organisation@.service from radiator@.service. What you need to do is to adjust radiator-organisation@.service file so that it has PartOf and WantedBy lines pointing to the new renamed radiator-organisation-instances.service file.

After setting up those renamed files, you will be able to command the group of instances the same way as above with system wide instances group. The only difference is that for example in this case you would use the same commands with differently named services and instances, for example:

systemctl enable radiator-organisation-instances radiator-organisation@auth radiator-organisation@proxy

systemctl start radiator-organisation-instances

systemctl stop radiator-organisation-instances

For more information

In case you have any questions, comments or feedback, please contact support@radiatorsoftware.com.

TNC19 Radiator technical workshop presentations available!

Terena Networking Conference 2019 (TNC19) is over as is our Radiator technical workshop, which was part of the conference. Here are all of Radiator Software presentations presented in the Radiator technical workshop. You are able to find these also on our SlideShare account, where we will upload also future public presentations about Radiator.

1) TNC19 Radiator Technical Workshop -- Introduction, what's new with Radiator (Software)

2) TNC19 Radiator Technical Workshop -- Using Radiator to ensure better SP/IdP connections to eduroam/govroam

3) TNC19 Radiator Technical Workshop -- Meet Radiator developers

Thank you to all Radiator technical workshop participants, we hope to see you again. We also will look into possibilities of repeating our technical workshop as a webinar together with TNC19 organisers for those who were not able to attend live.