Migrating from Ubuntu 18.04

Support in the form of updates for Triage setups on Ubuntu 18.04 has ended at the end of March 2023. Your existing setup will keep working, but no more updates for signatures and other components will be released.

Ubuntu 20.04 is the latest supported host operating system.

Contact us at support@hatching.io to request your new Ubuntu 20.04 mirror or do the following:

Append -20.04 to your existing 18.04 mirror to get your Ubuntu 20.04 mirror.

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

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

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 if any help is needed with the migration of Triage to a Ubuntu 20.04 setup.

Migrating Triage after an OS upgrade to Ubuntu 20.04

Multiple steps need to be taken after upgrading to Ubuntu 20.04. 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 20.04 mirror URL. Note that the upgrade process may have renamed hatching.list to hatching.list.distUpgrade -> rename it back. See Configuring apt for more information on what the contents should look like.

Update the package list by running the following command:

apt update

Install the new Hatching packages by running the following command:

apt dist-upgrade -o Dir::Etc::sourcelist=sources.list.d/hatching.list -o Dir::Etc::sourceparts=- -o APT::Get::List-Cleanup=0

Restart the following services: hatching-sandbox-net, triage-frontend

Migrate your configuration files as described at the following pages:

• triage.yaml -> Configuring Triage and Migrating backends to backends.yaml
• profiles.yaml -> Migrating deprecated Triage profiles.yaml.

Restart the following service: hatching-triage

Generating new analysis VMs.

• Follow the steps at Creating VM YAMLs and Deploying analysis VMs to generate new analysis VMs.
• VM creation can take a while.

Migrating Triage to a new Ubuntu 20.04 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/ if you intend to regenerate VMs (recommended).

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. You may need to regenerate the VMs used by Sandbox if the server hardware from before the backup does not match the new install. If not done, VM snapshots may fail to restore resulting in analyses failures.

4. Restore the PostgreSQL database.

   Ensure the triage-www database exists and is empty before restoring the backup. To restore, run: sudo -u postgres 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.