Instructions for updating the Security Server Software for Ubuntu Security Servers
This article provides instructions on how to update the software to the latest supported version on an Ubuntu Security Server connected to the Suomi.fi Data Exchange Layer test (FI-TEST) or production environment (FI).
NOTE! We only support software upgrades from the two previous X-Road versions!
Software upgrades from earlier versions directly to the new version have not been tested and may cause issues. We recommend keeping your software versions up to date at all times.
DO NOT use these instructions for installing a new Security Server. The update process is described in a separate set of instructions:
These instructions describe how to update the Data Exchange Layer software to version 6.9.x or later.
Before updating the Security Server Software
1. Back up the Security Server
Before you update the Security Server software to a new version, take thorough backups of the server.
When you have a snapshot of the Security Server’s disk or an otherwise comprehensive backup, you can restore the old version if problems occur in the update. At a minimum, back up the configuration of the Security Server through the UI. Back Up and Restore > BACK UP CONFIGURATION.
2. If necessary, update Ubuntu to version 18.04 LTS
In order to update the Data Exchange Layer software to version 6.20.1, the Ubuntu version 14.04 LTS must be updated to 18.04 LTS. This Ubuntu update is available for an existing Security Server if there is a console connection to the server. It is not safe to run the Ubuntu update using an SSH connection.
An alternative to updating an existing server is to install a new Ubuntu 18.04 LTS server alongside the old one and transfer the Security Server configuration and certificates from the old server to the new one. In that case, the old server’s public IP address and any other network or firewall settings should also be transferred to the new Security Server.
Updating the Security Server Software
NOTE! First, make sure that the update from the current software version of your Security Server to the new version is supported. We always support the two previous versions.
- Make sure you have backups and snapshots before you update.
- Check which version of X-Road your Security Server is using. The version is stated at the bottom of the Security Server graphical user interface when logged in. You can connect to the user interface at https://liityntapalvelimesi-nimi:4000
- On the Version Updates page, check which version of X-Road the Data Exchange Layer is using to see which version you should update your Security Server to.
- Check whether the version run by the Data Exchange Layer supports the current X-Road version of your Security Server at the NIIS version releases pageOpens in a new window.. Information on supported versions is provided in the Supported versions section in the page of the relevant version update.
- If the update to the version run by the Data Exchange Layer is not supported from the X-Road version run by your Security Server, please contact the support at palveluvayla@palveluvayla.fiOpens in a new window.. The administration of the Data Exchange Layer will provide you with instructions for the update.
- If the update to the version run by the Data Exchange Layer is supported from the X-Road version run by your Security Server, follow the steps below to update the software.
Update to software version 6.20.0 or later
1. Open an SSH session on the server. Retrieve the new signature key of the installation packages based on the environment in which you are performing the update.
Development environment (FI-DEV):
curl http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-dev-current/niis.public.asc | sudo apt-key add -Test environment (FI-TEST):
curl http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-test-current/niis.public.asc | sudo apt-key add -Production environment (FI):
curl http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-prod-current/niis.public.asc | sudo apt-key add -2. Edit the sources.list file that is located in the following directory path:
/etc/apt/sources.listIf the sources.list file does not yet contain the line
deb http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-env-current/packages stable mainwhere ‘env’ is the ID of the environment in use, the line is in the file xroad.list.
Edit the contents of the file to correspond to the environment as instructed below. The file is located in:
/etc/apt/sources.list.d/xroad.listDevelopment environment (FI-DEV):
Change the following row in the sources.list file (or in the xroad.list file)
deb http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-dev-current/packages stable mainto:
deb http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-dev-current/packages bionic-current mainTest environment (FI-TEST):
Change the following row in the sources.list file (or in the xroad.list file)
deb http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-test-current/packages stable mainto:
deb http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-test-current/packages bionic-current mainProduction environment (FI):
Change the following row in the sources.list file (or in the xroad.list file)
deb http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-prod-current/packages stable mainto:
deb http://www.nic.funet.fi/pub/csc/x-road/client/ubuntu-prod-current/packages bionic-current mainAs you can see, in all environments, the word ‘stable’ is replaced with ‘bionic-current’.
3. After you have retrieved the signature key and edited the xroad.list file, enter the following commands :
sudo apt-get update
sudo apt upgrade
Alternatively, you can use the command sudo apt upgrade instead of the command sudo apt-get upgrade --with-new-pkgs
Security Server Software post-update checklist
1. During the update installation, you might get warnings that old directories cannot be deleted (see sample error messages below). You can ignore these warnings, since they have no effect on the installation or operation of the Security Server. The warnings are associated with changes in packaging: the xroad-common package has been divided into several smaller packages and the directories are no longer owned by the xroad-common package.
Unpacking xroad-common (6.17.0-1) over (6.16.0-1) … dpkg: warning: unable to delete old directory ’/etc/xroad/ssl’: Directory not empty dpkg: warning: unable to delete old directory ’/etc/xroad/backup.d’: Directory not empty
2. Check the versions of the xroad packages in use by the following command:
sudo dpkg -l | grep xroad-The command lists the installed packages that start with ‘xroad’ and their version data.
3. For each package, verify that the installed version is now the updated one.
4. If the package versions are correct, continue to the next step. If any of the packages is still displayed as the old version, use the following command:
sudo apt upgradeVerify that all packages have been updated to the correct version and reboot the server.
5. Verify that all X-Road services are running. To do this, type:
systemctl list-units "xroad-*" "postgresql@*"The status of the services listed by the command should be start/running.
If some service did not start, you can start it manually by typing:
sudo service start6. When all services are running, test the operation of the server from the administration interface (https://server_name:4000).
Troubleshooting
The Security Server UI does not respond or gives an error message
1. Check whether the /tmp directory has been mounted with the noexec switch.
If the /tmp directory has been mounted with the noexec switch, the admin UI will not start, since it needs the /tmp directory to function.
Use the mount command to check this:
mountCheck whether the resulting printout contains the identifiers /tmp and noexec. Sample printout:
/dev/loop0 on /tmp type ext3 (rw,noexec,nosuid,nodev)If the printout contains /tmp and noexec (such as in the sample above), you need to modify the /etc/fstab file to delete the noexec switch. Furthermore, to apply the changes immediately, the directory must be remounted with the following command:
mount -o remount,exec /tmp