Gateway Hub ["Geneos"]
["Geneos > Gateway Hub"]["User Guide"]

Upgrade Gateway Hub


This document guides you through how to upgrade Gateway Hub from one version to the next.

These instructions cover v2.2.x and later.

In general, upgrades cannot be performed in the following circumstances:

  • Upgrades from any previous version to a 2.2.x version.

  • Upgrades between 2.2.x point releases.

Warning: When upgrading, data in Gateway Hub is transformed to be compatible with the latest version. Existing data is not preserved. If you may need to downgrade in the future, you must manually create a backup before upgrading.


To perform an upgrade, the following are required:

  • Installation machine, which must fulfil the Installation machine requirements. This does not have to be the machine used during the original installation of Gateway Hub.

  • The installation machine must be able to reach all nodes in the current Gateway Hub installation. However, Gateway Hub does not have to be running.

  • The same version of Gateway Hub must be installed on all nodes.

  • A valid installation configuration file.


Before upgrading your Gateway Hub make sure it is in a healthy state. To do this, check the Gateway Hub self monitoring metrics, and resolve any problems.

Beginning Gateway Hub 2.2.x, you can perform an upgrade by performing the following steps:

  1. Download the latest Gateway Hub binaries from ITRS Downloads to your installation machine.
    • The binaries are packaged as a .tar.gz file named hub-installer-<version>.tar.gz.
  2. Move the Gateway Hub.tar.gz file into a user writeable directory.
  3. Unpack the Gateway Hub binary using the command line.
    • This creates a folder called hub-installer-<version>.
  4. Run the hubctl setup upgrade <install_config_file> command from your installation machine.

When upgrading you can also perform reconfiguration, including options available only in the latest version. However, protected settings cannot be changed.

For more information about available commands, see hubctl tool.


If you are using Gateway and Active Console to view Gateway Hub self-monitoring metrics, ensure you are using the latest available include file when upgrading Gateway Hub. This is because Gateway Hub upgrades may include changes to the Collection Agent plugins being used to monitor your Gateway. For example, when upgrading from Gateway Hub version 2.3.x to version 2.4.x, the linux-infra plugin is replaced with the system plugin.

For the latest information about configuring self monitoring, see Gateway Hub integration.


When you perform an upgrade Gateway Hub preserves the full directory structure of the existing installation and creates a new structure for the latest version. You may manually delete the previous directory structure once the upgrade is complete, or you may prefer to keep it either for reference or in order to be able to restore your Gateway Hub to its previous state if you decide to revert to the previous version later.

Recall that, when upgrading, data in Gateway Hub is transformed to be compatible with the latest version. Existing data is not preserved so you must manually create a backup before upgrading. This is recommended if you might downgrade in the future.

If you later downgrade your Gateway Hub you can use a backup to restore your pre-upgrade data only.

Common issues

This section provides additional guidance for common issues encountered when performing an upgrade.

Registration with systemd

If the Gateway Hub orchestration service has been registered with systemd, you will need to mask the orchestration service when upgrading Gateway Hub.

For more information about registration with systemd, see Registration with systemd in Install.

To mask the orchestration service when upgrading:

  1. Mask and stop the orchestration service by running the following on each node:

    sudo systemctl mask hub-orchestration
    sudo systemctl stop hub-orchestration
  2. Perform the Upgrade steps.

  3. Unmask and restart the orchestration service by running the following on each node:

    sudo systemctl unmask hub-orchestration
    sudo systemctl start hub-orchestration