Centralised Gateways

Overview Copied

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 Copied

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 Copied

A Gateway 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, SSO Agent User Guide and Roles.

To authenticate the connection from Gateway to Gateway Hub, use one of the following methods:

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

Store Gateway binaries in Gateway Hub Copied

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:

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 Copied

Authenticated usage with a secure Gateway Hub Copied

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 Copied

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
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.

Obtain Gateway setup from Gateway Hub Copied

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:

To start the Gateway with an authenticated connection to the Gateway Hub, use the following command line options, replacing the parts in <> with the your information:

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.

Generate Gateway Hub API keys Copied

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 Copied

In this example:

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 Copied

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 Copied

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 or be named “Administrator” 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 Copied

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:

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 Downloads.

Queuing of Gateway tasks when connected to Gateway Hub Copied

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:

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

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:

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

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

Was this topic helpful?