How to Upgrade Security Server to Ubuntu 18.04 Using a Configuration Backup?

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

This document describes the steps required for migrating a stand-alone Security Server from an existing Ubuntu 14.04 LTS host to a new Ubuntu 18.04 LTS host. The migration is done taking a backup of the security server configuration on the Ubuntu 14.04 host and restoring the backup on the Ubuntu 18.04 LTS host. Please read carefully through the whole document before starting the upgrade process.

Alternative method: Security Server Ubuntu 14.04 to 18.04 In-place Upgrade.

Preparation

Connecting a hardware security module (HSM) to a new server may require additional steps that are not covered by these instructions.

  • Ensure that the X-Road software is at version 6.20.0/1 or 6.21.0.

  • On the current server, use the admin UI to take a backup of the security server configuration and download it to a safe location.

    • Note that the backup does not include X-Road admin user account(s).
  • In order to route traffic to the upgraded server after the upgrade is complete, prepare to update your network configuration.
    •  After the upgrade, you may need to change the upgraded server's public IP address(es) to match the old public addresses and/or update DNS,  firewall, NAT, or other network configuration so that other security servers and your information systems can reach the upgraded server.
    • The exact steps depend on your network setup and are not covered in this guide.
      • Note that if the publicly visible IP address of the upgraded security server changes, you may need to contact your X-Road Instance operator and/or other members for firewall rule changes.

Upgrade process

  • Do a clean install of security server software version 6.20.0/1 or 6.21.0 (N.B.! must be the same version from which the backup was taken) on Ubuntu 18.04 (see the X-Road Security Server Installation Guide for Ubuntu).
    • The admin UI and internal TLS certificates created during the installation process will be overwritten by the ones restored from the backup.
    • The X-Road admin user is not included in the backup (must be created manually).

  • Restore the security server configuration from the backup:
    sudo -iu xroad /usr/share/xroad/scripts/restore_xroad_proxy_configuration.sh -F -f <backup file>

Optionally, copy the messagelog database and archived log records from the old server

  • On the old server, stop the xroad-proxy and dump message log data using pg_dump (note that the size of the messagelog database can be large, so this can take time and a space).
    sudo service xroad-proxy stop
    sudo -iu postgres pg_dump -d messagelog -Fc -f <dump_file>
    (see https://www.postgresql.org/docs/9.3/app-pgdump.html for more information about creating a database dump)

  • Copy the dump to the new server and restore the database on the new server:
    sudo service xroad-proxy stop
    sudo -iu postgres pg_restore -d messagelog -c <dump_file>
    sudo service xroad-proxy start
    (see https://www.postgresql.org/docs/10/app-pgrestore.html for more information about restoring a dump)

  • Copy the archived message records (in /var/lib/xroad) to the new server.

Optionally, copy the operational monitoring database from the old server (if xroad-opmonitoring is installed)

  • On the old server, stop xroad-opmonitor and dump the database:
    sudo service xroad-opmonitor stop
    sudo -iu postgres pg_dump -d "op-monitor" -F c -f <dump_file>

  • Copy the dump to the new server and restore the database on the new server:
    sudo service xroad-opmonitor stop
    sudo -iu postgres pg_restore -d "op-monitor" -c <dump_file>
    sudo service xroad-opmonitor start


Switch over to the upgraded server (stop the old server and update your network configuration accordingly).