Central Server Ubuntu 14.04 to 18.04 In-place Upgrade.
This document describes the steps required for upgrading Central Server host from Ubuntu 14.04 LTS host to Ubuntu 18.04 LTS. The upgrade is a two-phase process; first from version 14.04 to 16.04 and then to version 18.04. 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.
Alternative method:Â How to Upgrade Central Server to Ubuntu 18.04 Using a Configuration Backup?
Preparations
Note that upgrading a system that uses a hardware security module has not been tested. Please verify that the HSM is compatible with Ubuntu 18.04 and check the HSM module documentation for upgrage instructions.
- Review the Ubuntu release notes and upgrade instructions:
- 14.04 → 16.04 https://wiki.ubuntu.com/XenialXerus/ReleaseNotes
- 16.04 → 18.04 https://wiki.ubuntu.com/BionicBeaver/ReleaseNotes
- 14.04 → 16.04 https://wiki.ubuntu.com/XenialXerus/ReleaseNotes
Update all packages to the latest versions:
apt update && apt full-upgrade Ensure that the X-Road software version is 6.20.0/1 or 6.21.0.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 14.04 to 18.04
Stop the central server before continuing to the actual upgrade: service xroad-jetty stop; service xroad-signer stop
The upgrade is a two-phase process; first from version 14.04 to 16.04 and then to version 18.04
- Install update-manager-core and software-properties-common if not already installed.
- Make sure the Prompt line in
/etc/update-manager/release-upgrades
is set toÂlts
(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 (the central server processes won't start after reboot since 16.04 and 18.04 use systemd and the startup scripts are still in upstart format).
Repeat the process to upgrade from 16.04 to 18.04.
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 9.3 (main) running on port 5432sudo pg_dropcluster --stop <version, e.g. 10> main
Upgrade the old database to version 10
:
sudo pg_upgradecluster 9.3 main
Clustered Central Server: Update the BDR repository to point to Ubuntu 18.04 packages
This step applies only to a clustered central server.
echo "deb https://apt.2ndquadrant.com/ bionic-2ndquadrant main" > /etc/apt/sources.list.d/bdr.list wget --quiet -O - https://dl.2ndquadrant.com/gpg-key.asc | apt-key add -
Update the X-Road package repository to point to the Ubuntu 18.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 trusty-current main" apt-add-repository "deb https://artifactory.niis.org/xroad-release-deb bionic-current main"
Alternatively, find the repository definition in /etc/apt/sources.list and edit it directly.
- (Optional) Remove the now unnecessary openjdk-r-ppa-trusty.* and nginx-stable-trusty.*Â -files from /etc/apt/sources.list.d/
Upgrade the packages
sudo apt update && sudo apt full-upgrade
Warnings like the following during the upgrade can be ignored:
Failed to stop xroad-jetty.service: Unit xroad-jetty.service not loaded.
invoke-rc.d: initscript xroad-jetty, action "stop" failed.
dpkg: warning: old xroad-jetty9 package pre-removal script subprocess returned error exit status 5
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@10-main.service loaded active running PostgreSQL Cluster 10-main * xroad-jetty.service loaded active running X-Road Jetty server xroad-signer.service loaded active running X-Road signer
*A clustered central server has PostgreSQL version 9.4
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 9.3 main
sudo apt purge postgresql-9.3
postgresql-9.5
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
Related articles