Central Server Ubuntu 20.04 to 22.04 In-place Upgrade.
This document describes the steps required for upgrading Central Server host from Ubuntu 20.04 LTS host to Ubuntu 22.04 LTS. Please read carefully through the whole document before starting the upgrade process. It is assumed that the reader is familiar with the Ubuntu Linux distribution and has experience of Ubuntu release upgrades and the central server is installed using the installation guide and has a local PostgreSQL database.
Preparations
If upgrading a system that uses a hardware security module: Please verify that the HSM is compatible with Ubuntu 22.04 and check the HSM module documentation for upgrade instructions.
Review the Ubuntu release notes and upgrade instructions:
Update all packages to the latest versions:
apt update && apt full-upgrade
Ensure that the X-Road software version is at least 7.2.0
In case of a central server cluster, ensure that all nodes have the same X-Road software version.
Recommended: Make sure that you have an up-to-date backup (or a virtual machine snapshot) of the server.
Use the admin UI to take a backup of the central server configuration and download it to a safe location.
This makes it possible to restore the server configuration if the upgrade fails for some reason.
Upgrading Ubuntu 20.04 to 22.04
Stop the central server and prevent it from starting on boot before continuing to the actual upgrade:
systemctl stop xroad-jetty xroad-signer
systemctl disable xroad-jetty xroad-signer
Install
update-manager-core
andsoftware-properties-common
if not already installed.Make sure the Prompt line in
/etc/update-manager/release-upgrades
is set tolts
(long-term support)Launch the upgrade tool with the command
sudo do-release-upgrade
Follow the on-screen instructions.
When the upgrade is finished, reboot when prompted.
Upgrading the X-Road software
Stand-alone Central Server: Upgrade the database
This step applies only to a stand-alone central server.
By default, the Ubuntu upgrade process creates empty database instances that should be removed before the old database is upgraded.
List the database instances with
pg_lsclusters
, and drop the extra ones.
Do not remove the version 12 (main) running on port 5432sudo pg_dropcluster --stop <version, e.g. 14> main
Upgrade the old database to version 14:
sudo pg_upgradecluster 12 main
Update the X-Road package repository to point to the Ubuntu 20.04 packages
Update the X-Road apt repository (remove old and add new):
apt-add-repository -r "deb https://artifactory.niis.org/xroad-release-deb focal-current main" apt-add-repository "deb https://artifactory.niis.org/xroad-release-deb jammy-current main"
Alternatively, find the repository definition in
/etc/apt/sources.list
and edit it directly.
Upgrade the packages
sudo apt update && sudo apt full-upgrade
Enable automatic startup and start central server
systemctl enable xroad-jetty xroad-signer
systemctl start xroad-jetty xroad-signer
Verify that the central server services are running and the system is responding
systemctl list-units "xroad-*" "nginx*" "postgresql@*"
UNIT LOAD ACTIVE SUB DESCRIPTION
nginx.service loaded active running A high performance web server and a reverse proxy server
postgresql@14-main.service loaded active running PostgreSQL Cluster 14-main
xroad-base.service loaded active exited X-Road initialization
xroad-jetty.service loaded active running X-Road Jetty server
xroad-signer.service loaded active running X-Road signer
Stand-alone central server only: Drop old database and obsolete packages
After verifying that the database upgrade was successful, drop the old database and remove obsolete PostgreSQL packages.
sudo pg_dropcluster 12 main
sudo apt purge postgresql-12
sudo apt autoremove
Troubleshooting
If recovery from a upgrade failure is not possible and there is a backup/snapshot available, one can restore it and start over.
If all else fails, do a clean Ubuntu installation and restore the security server configuration from the backup
For cluster recovery instructions, see X-Road Central Server HA Installation Guide