Migrating to a newer Ubuntu version.

When to migrate

Support for each Ubuntu server version is limited until the date specified on the Server OS Support section.

Your existing setup will keep working, but no more updates for signatures and other components will be released.

Ubuntu 24.04 is the latest supported host operating system.

Prerequisites

It is recommended to always make a backup of your data. See Creating data and configuration backups.

Append or replace the version in your mirror URL with the Ubuntu version you are migrating to. E.G -24.04 or 22.04. This URL will be the new mirror URL.

Example: https://deploy.hatching.io/pkg/company/XXXXXXXXX-20.04 becomes https://deploy.hatching.io/pkg/company/XXXXXXXXX-24.04.

Contact us at support@hatching.io if you have trouble with your new mirror.

This page describes how to update your Triage setup to run on new Ubuntu version.

There are extra steps when migrating to a new server or new install compared to upgrading the already installed Ubuntu version. An important difference is to make backups of specific data before performing a reinstall.

Please contact us at support@hatching.io you are having trouble with the migration.

Migrating Triage after an OS upgrade

Multiple steps need to be taken after upgrading Ubuntu to a new version. We'll assume you've upgraded using do-release-upgrade and rebooted the machine succesfully.

Replace the old Ubuntu package mirror URL in /etc/apt/sources.list.d/hatching.list with your new Ubuntu mirror URL.

See Configuring apt for more information on what the contents should look like.

Note that the upgrade process may have renamed hatching.list to hatching.list.distUpgrade -> rename it back.

Update the package list by running the following command:

apt clean
apt update

Re-install all installed Hatching packages with their version-specific package by running the following command:

apt -o Dir::Etc::sourcelist="sources.list.d/hatching.list" -o Dir::Etc::sourceparts="-" install --reinstall $(dpkg-query -W -f='${Package} ')

Reload systemd service files and restart the following services: 

systemctl daemon-reload
systemctl restart hatching-sandbox-net
systemctl restart hatching-sandbox
systemctl restart hatching-vms
systemctl restart hatching-triage

Generating new analysis VMs.

Multiple PostgreSQL servers

Updating your OS and then re-installing packages may result in multiple installed versions of PostgreSQL.

It is recommended to keep the latest version and migrate your database to it.

Migrating Triage to a fresh Ubuntu install

Migrate to a new server is possible as an alternative to an OS upgrade. On the new server, install Triage as you would in the Triage install, using the configuration files from the existing setup.

When the components are installed, move all files from /var/lib/{triage,sandbox,triage-frontend}/ to the new server. Ensure the file ownership matches the existing setup.

The following data should be backed up:

  • Configuration file contents (all YAML configuration files in /var/lib/{triage,sandbox,triage-frontend}/).
  • The PostgreSQL database containing information about analyses and users (the database configured in /var/lib/triage-frontend/frontend.yaml).
  • The analyses stored on disk (the /var/lib/triage/analyses directory).

The PostgreSQL database is needed to be able to view the old analyses in the UI or using the API.

Creating data and configuration backups

  1. Backup/copy all YAML configuration files from the old install/server.

    These files are (some might not be present in older setups):

    • /var/lib/triage/: *.yaml
    • /var/lib/sandbox/: *.yaml, vms/*.yaml
    • /var/lib/triage-frontend/: *.yaml

  2. Backup and restore the PostgreSQL database on the old install/server.

    The default database name is triage-www. The name can be confirmed by looking at the value of dbname in the connection DSN in /var/lib/triage-frontend/frontend.yaml.

    Create a dump of the database by running sudo -u postgres pg_dump -d triage-www > database_dump.sql. Verify that the dump is not empty.

    Move/copy the database dump the new install/server so it can be restored at a later step.

  3. Backup/copy/move the remaining contents of /var/lib/triage of the old install/server to the new install/server.

  4. Backup/copy/move the remaining contents of /var/lib/sandbox of the old install/server to the new install/server. You can skip backing up managedvms/ and hatchvm/ (VM storage locations). VMs must be regenerated after upgrading.

Restoring from a backup

Follow the Triage install steps and use the contents of the configuration files that have been backed up when an install step mentions this file.

Start restoring data after the Triage setup is complete.

  1. Copying the configuration files back to the new install.

  2. Copying the data from /var/lib/triage and /var/lib/sandbox on the new install.

    Ensure the triage user and group own the analyses directory and the owner has read and write access after copying the data. This can be achieved by running chown triage:triage /var/lib/triage/analyses and chmod 755 /var/lib/triage/analyses.

    Restart Triage by running systemctl restart hatching-triage.

  3. Restore the PostgreSQL database.

    Ensure the triage-www database exists and is empty before restoring the backup. To restore, run: sudo -u triage-www psql triage-www < database_dump.sql.

    The dump includes things such as the database owner, verify that this matches the database user in /var/lib/triage-frontend/frontend.yaml on the new install.