Skip to main content

Software updates & lifecycle management

Understand appliance updates​

Why update?​

Bugs and security vulnerabilities are inevitable in any software. Anapaya is committed to providing timely updates to address these issues, as well as to introduce new features and enhancements. Regular updates are essential to ensure the security, stability, and performance of your Anapaya appliance.

Subscribe to the release notes newsletter to stay informed about the latest updates and improvements to the Anapaya appliance.

Package types​

The Anapaya appliance uses two type of packages:

  • SCION/Appliance package: The Appliance package (sometimes called SCION package) contains the Anapaya SCION software and tightly integrated third-party software. The Appliance package is enabling the SCION functionality on the appliance.
  • System package: The system package contains the operating system and other system-level components, that are required to be able to run the SCION software on the appliance. Most of the components in the system package are tracking the upstream Ubuntu release. Some components are specific to the Anapaya appliance.

The main reason for different package types is different release cycles.

During the upgrade, first install the System package, and then the Appliance package.

Both package types follow semantic versioning with the following patten <major>.<minor>.<patch>. For the Appliance package versions can generally be updated with little consideration. For the system package, an increase of the major version indicates a new OS version, a new base image must be installed. To install a system package with version <major>.<minor>.X, first install the system package with version <major>.<minor>.0, e.g., to install the system package 2.16.4, first install the system package 2.16.0.

Release notes​

Read the release notes before performing any updates. The release notes provide specific guidance on what to expect from the update, including new features, bug fixes, and any potential issues that may arise during the update process.

Click the links below to access the release notes:

Package signatures​

The Appliance and System packages are signed to ensure their integrity and authenticity. The Anapaya base image has the verification key pre-installed, so that during the installation process the Appliance can verify the signature of the packages. See the Managing the verification key section for more information.

Expected impact​

System and Appliance package updates will cause traffic interruptions, it is therefore recommended to schedule maintenance windows. Some packages require a reboot of the appliance after installation. We recommend to have a high availability setup, appliances in such a setup can be updated independently and may run different System and Appliance package versions. So you can update one appliance, see it in action and then schedule the update of another appliance in the same cluster.

Prepare the update​

The update can either be done via the Anapaya Console or via the Appliance CLI. Going via the Console is much simpler and recommended. Below the steps for both methods are described.

  1. Select the version to install

    We recommend to always install the latest version of the Appliance and System packages, as they contain the latest features, bug fixes, and security updates. For the System package, you need to make sure that if you are installing a version <major>.<minor>.X, you first install the version <major>.<minor>.0 if you are not already running a version <major>.<minor>.0 or higher.

    For example, if you are running the System package version 2.14.12, you can update to 2.14.13 or 2.16.0, but not to 2.16.1. To update to 2.16.1, first update to 2.16.0, then to 2.16.1. Note that jumping over versions is ok, e.g. you can update from 2.14.12 to 2.16.0 directly.

    You can always update the Appliance package to the latest version without any intermediate steps, unless otherwise stated in the release notes.

    The Appliance package requires a certain System package version to be installed, check the release notes for the specific requirements.

    The current latest versions are:

  2. Check the current version

    1. Open the appliances view by clicking on Appliances in the left sidebar.
    2. Select the appliance you want to update.
    3. The current versions are displayed below the appliance name. In the example below, the appliance is running the v0.39.5 version of the Appliance package and v2.16.0 of the System package. Console version

  3. Check release notes

    Review the release notes for the Appliance package and System package to understand the changes and potential tasks to be done as part of updating. The release notes can be found in the Appliance releases and System releases sections.

  4. Download packages to install

    By pre-downloading the packages, you can keep the time of the update during the maintenance window as shot as possible.

    1. Open the appliances view by clicking on Appliances in the left sidebar.
    2. Select the appliance you want to update.
    3. Click the Software button on top of the appliance title.
    4. Click the Trigger Download button in the Software view.
    5. Select the packages to download and confirm the download by clicking the Trigger Download button.

  5. Record health status

    Record the health status of the appliance before the update, to check after the update if anything changed.

    1. Open the appliances view by clicking on Appliances in the left sidebar.
    2. Select the appliance you want to update.
    3. Click the Health button on top of the appliance title.
    4. Record the health status, either with a screenshot or by copying the health status to a text file.

Update the appliance​

  1. Trigger the update

    1. Open the appliances view by clicking on Appliances in the left sidebar.
    2. Select the appliance you want to update.
    3. Click the Software button on top of the appliance title.
    4. Click the Trigger installation button in the Software view.
    5. Select the packages and the time and trigger the installation by clicking the Trigger installation button.

  2. Check the installation status

    1. Open the appliances view by clicking on Appliances in the left sidebar.
    2. Select the appliance you want to update.
    3. Click the Software button on top of the appliance title.
    4. Click on Software History the see the ongoing and past installations.

  3. Reboot the appliance

    Check if a reboot is required after the installation:

    1. Check if kernel version has changed:

      The following command shows the current kernel version.

      uname -r

      The following command shows the kernel versions installed on the appliance.

      ls -l /boot/vmlinuz-*

      If they differ, reboot the appliance.

    2. Check if the reboot_required flag is set:

      ls /var/run/reboot-required

      If the file exists, reboot the appliance.

  4. Check the health status

    1. Open the appliances view by clicking on Appliances in the left sidebar.
    2. Select the appliance you want to update.
    3. Click the Health button on top of the appliance title.
    4. Check for any health issues that might have arisen during the update process.

Troubleshooting​

Roll back to previous release​

To roll back to a previous Appliance package version, you simply install the previous version, using the same instructions as for the update.

System package cannot be rolled back

Rolling back to a previous System package version is currently not supported.

Inspect the installation logs​

Inspect the installer logs by issuing the following command on the appliance:

journalctl -u appliance-installer.service -n 200 -f

The -n 200 option shows the last 200 lines of the log, and the -f option follows the log for new messages.

Managing the verification key​

Updating the verification key​

By default, the verification key is already installed on the appliance. Should you ever need to manually change the verification key, you can do so by doing the following steps:

Steps to update the verification key

  1. Download the verification key and copy it to the appliance under /tmp/keys.json.

    • Download the key

      curl https://releases.anapaya.net/keys.json -o keys.json

    • Copy the verfication key to the appliance

      scp keys.json <appliance>:/tmp/keys.json

  2. Install the verification key on the appliance using the appliance-cli.

    # Install the verification key on the appliance
    appliance-cli post software/keys </tmp/keys.json
    # List the currently installed verification keys
    appliance-cli get software/keys

Handling a key compromise​

While Anapaya goes to great lengths to ensure the private signing keys are secure, we have defined a process for the unlikely case of key compromise. If a private key is compromised, Anapaya will inform all affected parties via email. The compromised key will be removed from our webpage (releases.anapaya.net), and our webpage will explicitly state which key was tainted.

Follow this process:

  1. Update the verification key on the appliance by following the steps in the Updating the verification key section.
  2. Reinstall the anapaya-scion and anapaya-system packages following the steps in the Update the appliance section.

With this process, you can ensure that the installed public keys are up-to-date and that the Anapaya software packages can successfully be verified.

Install custom apt packages​

NOT RECOMMENDED

The installation of custom packages might interfere with the Anapaya-managed packages. The following configuration changes might lead to issues with the appliance installer when upgrading to a newer software version and cause the system to break. We highly recommend avoiding custom package installation, unless absolutely necessary.

By default, it is not possible to install packages that are not part of the System package package. However, there might be special cases that require custom package repositories and additional packages to be available. In such cases, follow the steps below:

Steps to install custom apt packages

The following commands need to be run as root, or with sudo on the appliance.

  1. Edit the sources list file:

    vim /etc/apt/sources.list.d/jammy.list

  2. Add the following content to the file:

    deb http://archive.ubuntu.com/ubuntu jammy main restricted
    deb http://archive.ubuntu.com/ubuntu jammy-updates main restricted

    deb http://archive.ubuntu.com/ubuntu jammy universe
    deb http://archive.ubuntu.com/ubuntu jammy-updates universe

    deb http://archive.ubuntu.com/ubuntu jammy multiverse
    deb http://archive.ubuntu.com/ubuntu jammy-updates multiverse

    deb http://security.ubuntu.com/ubuntu jammy-security main restricted
    deb http://security.ubuntu.com/ubuntu jammy-security universe
    deb http://security.ubuntu.com/ubuntu jammy-security multiverse

  3. Update the package list:

    apt update

  4. Install the custom package:

    apt install <package>

  5. Remote the custom sources list file:

    rm /etc/apt/sources.list.d/jammy.list