Geneos ["Geneos"]
You are currently viewing an older version of the documentation. End of life for version 5.x.x is scheduled for 30 September 2025.
If you are currently using version 5.x.x, we advise you to upgrade to the latest version before the EOL date. You can find the latest documentation here.

Centralised Gateways User Guide

Overview

As Geneos estates have gotten larger, the number of Gateways in use is increasing. This in turn carries a linear increase in administrative effort. To help simplify the administration of these large estates, Gateway configuration files can be stored centrally in Gateway Hub. This simplifies the process for configuring Geneos as it removes the need to deal with storing and governing externally hosted files.

Gateway Hub can function as a centrally accessible repository for Gateway setup and include files. You can use the Gateway to create a setup and upload include files to Gateway Hub. This enables other Gateways in your organisation to obtain their setup information from Gateway Hub.

Prerequisites

Your Gateway must be running on a Linux system and at least version 5.0 to obtain files stored in Gateway Hub.

Your Gateway Hub must be at least version 1.6 to store Gateway setup and include files.

Authentication

You can connect to a Gateway Hub without authentication. This is useful in testing and development environments. However, this is not secure and you should always use the SSO Agent or an API key in production environments. For more information, see Connect to Gateway Hub in Gateway Hub Quickstart, SSO Agent User Guide and Roles.

To connect to Gateway Hub securely, use one of the following methods:

  • Create a Kerberos keytab for the Gateway user. This keytab is used to request tokens from Gateway Hub. You can then connect to Gateway Hub securely by starting Gateway with the --kerberos-principal <principal> and --kerberos-keytab <keytab> options.

  • Create a Gateway Hub API key for the Gateway user. This API key is used to request tokens from Gateway Hub. You can then connect to Gateway Hub securely by starting Gateway with the -app-key <filename> option.

You can download the latest versions of Gateway, Gateway Hub, and SSO Agent from ITRS Downloads.

Store Gateway binaries in Gateway Hub

You can use the upload_gateway_binary script, included with Gateway, to store Gateway binaries in the central Gateway Hub. The Gateway Hub requires Gateway binaries to perform validation of Gateway setups stored on the Hub.

The upload_gateway_binary script is located in resources/helper-scripts in the Gateway directory.

The script has the following command-line options:

Option Description
-h Returns help message.
--gateway-hub <url> URL used to connect to Gateway Hub.
--file <file> File to upload. This should be a Gateway tar.gz package file.
--sso-agent <url> URL used to connect to the SSO Agent, if the SSO Agent is not running inside of Gateway Hub.
--kerberos-principal <principal>

Username the Gateway uses when connecting to Gateway Hub.

Required when connecting to a Gateway Hub using SSO. See Configure single sign-on (SSO).

Must not be set if connecting without authentication.

--kerberos-keytab <keytab>

Optional. Credentials the Gateway uses when connecting to Gateway Hub.

Required when connecting to a Gateway Hub using SSO. See Configure single sign-on (SSO).

Must not be set if connecting without authentication.

   

Note: If you do not specify a keytab when connecting securely you will be prompted for your SSO password.

Caution: Do not upload Gateway binaries built for Red Hat Enterprise Linux version 8 to Gateway Hub, this will result in an error.

Example commands

Authenticated usage with a secure Gateway Hub

To connect to a Gateway Hub using SSO authentication:

./upload_gateway_binary --gateway-hub <hub-url> --file <binary-file> --kerberos-principal <principal> --kerberos-keytab <keytab>

Note: If you run the script with missing parameters, the script will return an error message to alert you to the missing parameter.

The script will return a list of stored binaries on success:

Hub now supports these Gateway versions
 RA5.0.0-191021

Unauthenticated usage with an insecure Gateway Hub

To connect to a Gateway Hub without authentication:

./upload_gateway_binary --gateway-hub <hub-url> --file <binary-file>

The script will return a list of stored binaries on success:

Hub now supports these Gateway versions
 RA5.0.0-191021

Obtain Gateway setup from Gateway Hub

After creating a Gateway setup on Gateway Hub, you can start the Gateway and obtain setup files stored in Gateway Hub. To do this, you must start the Gateway with the following command line options, replacing the parts in <> with the your information:

  • -gateway-name <name> — Name of the Gateway setup. When this option is used, and no setup file is specified, then Gateway fetches the named setup from Gateway Hub. For more information, see Command line options in Gateway Installation Guide.
  • -gateway-hub <URL> — URL of the Gateway Hub. Only one URL is supported.

To connect to Gateway Hub securely, you must start the Gateway with the following command line options, replacing the parts in <> with the your information:

  • If using Kerberos for authentication:
    • -kerberos-principal <name> — Principal that the Gateway uses to request an SSO Token.
    • -kerberos-keytab <keytab> — Path to the file that stores the Kerberos keytab for the principal defined in -kerberos-principal <name>.
    • -sso-agent <URL> — Optional. URL of the SSO Agent providing an SSO Token to use with Gateway Hub. This is only required if you are not using the SSO Agent on the default port of the Gateway Hub node.
  • If using an API key for authentication:
    • -app-key <filename> — Path to the file that stores the Gateway Hub API key.

You can also place these command line options in a file for the Gateway to read at start up. See Command line options.

If successful, the Gateway starts and acquires its main setup and all includes from Gateway Hub.

Note: A Gatewaycannot use both local files and files stored on Gateway Hub.

Generate Gateway Hub API keys

You can generate API key credentials from the Application keys page in the Gateway HubWeb Console. API key credentials are composed of a client_id and a client_secret. You must use these credentials to create the key file used to start your Gateway. For more information, see Application Keys.

To create an API key file, use the following command:

./gateway2.linux_64 -store-app-key <filename> <client_id> <client_secret>

Example start-up command

In this example:

  • We want to start a Gateway with the name New Gateway from Gateway Hub.
  • The Gateway Hub URL is https://hub.example.com:8080.
  • The Kerberos principal is user@LDN.ITRS.
  • The path to the Kerberos keytab is user.keytab.

The command to start the Gateway is the following:

$ gateway2.linux_64 -gateway-name "New Gateway" -gateway-hub https://hub.example.com:8080 -kerberos-principal user@LDN.ITRS -kerberos-keytab user.keytab  

Note: If you have configured the Gateway to connect without authentication, then you must omit the Kerberos principal and keytab arguments.

Automatic registration of Gateways with Gateway Hub

When you start a Gateway using centralised configuration, it will request the setup file from Gateway Hub associated with the gateway-name specified in the start command. If there is no setup file corresponding to the specified gateway-name then a new minimal setup file will be created, containing only the gateway-name, and stored in the Gateway Hub. This minimal file will be provided to the new Gateway and you can then edit the Gateway setup using the Gateway Setup Editor.

Edit the Gateway configuration

Once your Gateway has started and acquired its setup from Gateway Hub, the Gateway configuration can be edited using the Gateway Setup Editor provided the following is true:

Note: If authentication is disabled, the GSE user does not need to be SSO authenticated. However, if Gateway authentication is enabled, the user must be an SSO user to edit the Gateway setup.

When validating or saving a setup, the Gateway sends a validation or save request to Gateway Hub. The Gateway waits a specified number of seconds for Gateway Hub to respond before timing out. The request may time out if the Gateway Hub is busy responding to other requests. The number of seconds the Gateway waits before timing out is specified using the -gateway-hub-timeout command line option on Gateway start up. See Command line options.

Any edits to the Gateway configuration using the GSE are saved to Gateway Hub.

Lock the Gateway configuration

The Gateway Setup Editor can lock resources directly in Gateway Hub for Gateway Hub-enabled Gateways. To do this, your Geneos components must be set up accordingly:

  • Gateway Setup Editor is at least version 5.0.
  • Gateway is at least version 5.0.
  • Gateway Hub is at least version 1.6 and configured with SSO authentication.

Note: To lock a configuration, you must be logged in as an SSO user. This is required even when Gateway authentication is disabled.

The latest versions of all components can be obtained from ITRS Downloads.

Queuing of Gateway tasks when connected to Gateway Hub

The Gateway queues requests, allowing it to keep processing and avoid setup change clashes while waiting for a response from Gateway Hub. The Gateway queues the following actions so that they do not occur simultaneously:

  • Gateway Setup EditorValidate.
  • Gateway Setup EditorApply.
  • USR1 Reload.
  • Reload due to Hot Standby synchronisation.
  • Reload due to timer.
  • Reload due to Gateway command.

If the Active Console/Gateway Setup Editor connection drops, any queued tasks are cancelled if they are:

  • Queued but not started.
  • Started and waiting for Gateway Hub to become available.

Note: If Gateway Hub has started to process a Validate or Save before a connection drops, these will run to completion on Gateway Hub.

The queue tasks that can be cancelled due to a connection drop are:

  • Gateway Setup EditorValidate.
  • Gateway Setup EditorApply.
  • Cmd setup.

If there are any queued setup tasks, the <protocol>://<host>:<port>/rest/setup/validate query returns 429 (Too Many Requests).