Geneos

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.

SSO Authentication

You should set up the SSO Agent when connecting a Gateway to a Gateway Hub. See SSO Agent User Guide.

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 in production environments.

A Kerberos keytab should be created for the Gateway user. This is used to request tokens from Gateway Hub.

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.

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 to acquire from Gateway Hub.
  • -gateway-hub <URL> — URL of the Gateway Hub. Only one URL is supported.
  • -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.

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 Gateway cannot use both local files and files stored on Gateway Hub.

Example 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 Editor Validate.
  • Gateway Setup Editor Apply.
  • 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 Editor Validate.
  • Gateway Setup Editor Apply.
  • Cmd setup.

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