Geneos
Geneos


Note: Centralised Configuration for Gateways is available as a technology preview. This feature requires Gateway Hub, and we are likely to make further enhancements to both Gateway and Gateway Hub that may not be compatible with previous versions.

Recommended Reads

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 4.11 to obtain files stored in Gateway Hub.

Your Gateway Hub must be at least version 1.3 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.

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.

Create a Gateway setup on Gateway Hub

A script is provided as part of the Gateway package to allow you to create a Gateway setup on Gateway Hub. You can optionally specify a main Gateway setup file to be uploaded for the Gateway.

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

The script has the following command-line options:

Option Description
-name <gateway-name> Name of the Gateway to be created.
-file <filename>

Optional. Main setup file for the Gateway to be uploaded to Gateway Hub.

Caution: The main setup file cannot reference any include files. Include files must be added using the Gateway Setup Editor once the Gateway is running.

-gateway-hub <URL> URL of the Gateway Hub. Only one URL is supported.
-sso-agent <URL>

Optional. URL of the SSO Agent providing an SSO Token to use with Gateway Hub.

Required if you are not using the SSO Agent on port 9999 of the Gateway Hub node.

-kerberos-principal <name>

Optional. Principal used to authenticate through Kerberos.

If you do not provide this, the name of the user running the script is used.
-kerberos-keytab <keytab>

Optional. Path to the file that stores the Kerberos keytab for the principal defined in -kerberos-principal <name>.

If you do not provide this, you are prompted for a password.
-version <gateway version>

Optional. Gateway version number.

Default is GA4.11.

To create a Gateway setup on Gateway Hub, run add_gateway on the command line replacing the parts in <> with the your information.

Note: If a main Gateway setup file is supplied using -file, the setup file must not reference any Gateway include files. These must be added by using the GSE against a Gateway with the setup stored in Gateway Hub.

If successful, the script returns the id of the Gateway setup created, and informs you of the command line options required to start a Gateway with the setup from Gateway Hub. For more information, see Example command below.

Example command

Example 1

In this example:

  • We want to create a Gateway with the name New Gateway.
  • 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 run the script is the following: 

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

The command line returns the following:

Performing kinit using keytab user@LDN.ITRS
Gateway : New Gateway has been created. Its id is 1
In order to start the gateway please use the following command line options

> gateway2.linux_64 -gateway-id 1 -gateway-hub https://hub.example.com:8080 -kerberos-principal "user@LDN.ITRS" -kerberos-keytab "user.keytab"

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-id <ID> — ID of the Gateway setup to acquire from Gateway Hub. The ID is obtained from when you Create a Gateway setup on 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 port 9999 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 setup ID 99 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-id 99 -gateway-hub https://hub.example.com:8080 -kerberos-principal user@LDN.ITRS -kerberos-keytab user.keytab

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 4.12.
  • Gateway is at least version 4.12.
  • Gateway Hub is at least version 1.4 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).