Configuration Proxy Ubuntu 14.04 to 18.04 In-place Upgrade.

Owned by Petteri Kivimäki
Last updated: Apr 25, 2019

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

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:

    • 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. Stop xroad-signer and take backup of /etc/xroad directory and download it into a safe place. It is possible to restore the configuration to a new host if the upgrade fails.


sudo service xroad-signer stop
sudo tar cvf $HOME/confproxy-backup.tar /etc/xroad

  • Recommended: Make sure that you have an up-to-date backup (or a virtual machine snapshot) of the server.

Upgrading Ubuntu 14.04 to 18.04

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.
    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 (the configuration proxy 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

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-signer.service: Unit xroad-signer.service not loaded.
invoke-rc.d: initscript xroad-signer, action "stop" failed.
dpkg: warning: old xroad-signer package pre-removal script subprocess returned error exit status 5

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-base                   6.20.0-1.ubuntu18.04 amd64        X-Road base components
ii  xroad-confclient             6.20.0-1.ubuntu18.04 amd64        X-Road configuration client components
ii  xroad-confproxy              6.20.0-1.ubuntu18.04 all          X-Road configuration proxy
ii  xroad-nginx                  6.20.0-1.ubuntu18.04 amd64        X-Road nginx component
ii  xroad-signer                 6.20.0-1.ubuntu18.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-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
[INFO] [12/18/2018 15:20:35.923] [main] [akka.remote.Remoting] Starting remoting
[INFO] [12/18/2018 15:20:36.117] [main] [akka.remote.Remoting] Remoting started; listening on addresses :[akka.tcp://ConfigurationProxyUtil@127.0.0.1:39772]
[INFO] [12/18/2018 15:20:36.118] [main] [akka.remote.Remoting] Remoting now listens on addresses: [akka.tcp://ConfigurationProxyUtil@127.0.0.1:39772]
Configuration for proxy 'EXAMPLE'
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 18.04 host (see the Configuration Proxy Manual)

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

      Example
      sudo systemctl stop xroad-signer nginx
sudo tar xvf confproxy-backup.tar -C /
sudo systemctl start xroad-signer nginx
sudo -iu xroad signer-console login-token 0
PIN:***********