Configuration Proxy Ubuntu 20.04 to 22.04 In-place Upgrade.

This document describes the steps required for upgrading a Configuration Proxy 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.

Preparations

If you use a hardware security module, please verify that the HSM is compatible with Ubuntu 20.04 and check the HSM module documentation for upgrade instructions.

Upgrading Ubuntu 20.04 to 22.04

  • Install update-manager-core and software-properties-common if not already installed.
    apt install update-manager-core software-properties-common

  • 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.

Upgrading the X-Road software

Update the X-Road package repository to point to the Ubuntu 22.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

Verify the upgrade

Check that all services are running and activate the security tokens if xroad-autologin is not configured.

Example output

$ sudo dpkg -l | grep "xroad*" ii xroad-autologin 7.2.0-1.ubuntu22.04 all Automatic token pin code entry ii xroad-base 7.2.0-1.ubuntu22.04 amd64 X-Road base components ii xroad-confclient 7.2.0-1.ubuntu22.04 amd64 X-Road configuration client components ii xroad-confproxy 7.2.0-1.ubuntu22.04 all X-Road configuration proxy ii xroad-nginx 7.2.0-1.ubuntu22.04 amd64 X-Road nginx component ii xroad-signer 7.2.0-1.ubuntu22.04 amd64 X-Road signer component $ sudo systemctl list-units "xroad*" nginx.service UNIT LOAD ACTIVE SUB DESCRIPTION nginx.service loaded active running A high performance web server and a reverse proxy server xroad-base.service loaded active exited X-Road initialization xroad-signer.service loaded active running X-Road signer # activate security token(s) $ sudo -iu xroad signer-console login-token 0 PIN:*********** $ sudo -iu xroad confproxy-view-conf -a Configuration for proxy 'PROXY1' Validity interval: 600 s. anchor.xml ================================================== (... output truncated ...)

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 you have the configuration backup available:

    • Install a new configuration proxy to a Ubuntu 22.04 host (see the Configuration Proxy Manual)

    • Restore the configuration and activate the security token(s).

      Example