Gateway Hub Quickstart

Overview Copied

You can connect Gateway and Gateway Hub to share data and centralise administration.

You must have at least version 4.12 of both Active Console and Gateway.

Connecting to a Gateway Hub allows you to:

• Perform anomaly detection.
• Store Geneos metrics and events and retrieve them with an Open API.
• Use centralised configuration to manage Geneos at scale.
• Visualise data using a web-based UI, the Web Console.

For more information see the Introduction to Gateway Hub and Gateway Hub Configuration.

Intended audience Copied

This guide is intended for Geneos users that want to connect to Gateway Hub. Before you proceed, we recommend that you read about Gateway Hub Prerequisites.

Connect to Gateway Hub Copied

Connect using the Gateway Setup Editor Copied

To connect a Gateway to Gateway Hub and share data follow these steps:

1. Open Active Console.
2. Double-click the Gateway you wish to configure with Gateway Hub. This opens the Gateway Setup Editor (GSE).
3. In the GSE, double-click in the Navigation tree. This creates the Gateway Hub section.
4. In the Gateway Hub section: 1. In Publishing address, add the host name and port of one of your Gateway Hub Kafka brokers. Once you have connected, Gateway will fetch the locations of all existing brokers from Gateway Hub. The default address is <hostname>:9092. 2. In REST address, add the REST address location of Gateway Hub. The REST address uses HTTPS. The default REST address is https://<hostname>:8081.
5. You must configure security in Additional Settings by specifying the location of the Gateway Hub CA certificate. You can obtain the certificate file from <hub_home>/tls/trust-chain.pem on any Gateway Hub node.

6. Click Validate current document .
7. Click Save current document .

When configuring Gateway Hub connections in Gateway Setup Editor, note the following:

• The trust-chain.pem file used by Gateway Hub nodes is either extracted from hub.pem you provided when installing Gateway Hub or generated by the installer if no hub.pem is provided. The trust-chain.pem file contains the CA certificate used to sign Gateway Hub certificates and it’s full trust chain.
• Additional Settings are entered using the same syntax as a Java properties file, so that each line specifies a key-value pair. Any global setting (other than callbacks) defined in the librdkafka documentation can be used by prefixing their names with kafka.. For more information about Kafka Additional Settings, see publishing > additionalSettings in Publish to Kafka.

For more details, see Gateway Hub Configuration.

Caution

Gateway Hub will reject metrics from Gateway samplers or dataviews that include the / character in their name.

Connect using the command line Copied

You can connect to Gateway Hub by using the -gateway-hub <REST URL> command line option when starting the Gateway. The URL specified here will take precedence over any REST address value specified in the Gateway Setup Editor. For more information, see Centralised Gateways User Guide.

Note

To use anomaly detection features you must start the Gateway in centrally configured mode.

Connect securely using SSO or API keys Copied

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

In order to use Gateway Hub for centralised configuration or to perform anomaly detection, you should connect securely.

For more information about secure connections, see SSO Agent User Guide, Gateway Hub SSO Agent, and Application Keys.

For more information about these features, see Centralised Gateways User Guide, Anomaly Detection, and Data Sets (Time series).

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:

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

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:

Monitor Gateway Hub Copied

It is often useful to be able to monitor Gateway Hub from your Active Console.

You can use the Gateway Hub data Gateway plug-in to monitor the status of the connection between Gateway and Gateway Hub. For more information, see Gateway Hub data in Gateway Plug-Ins.

You can also monitor Gateway Hub itself using the metrics collected by its internal Netprobe. For more information, see Gateway Hub integration.

View metrics in Active Console Copied

To view historical metrics using data from the Gateway Hub via the Active Console, follow these steps:

1. In the Active Console, navigate to a dataview.
2. In the dataview, right-click a cell you want to view historical data for.
3. Navigate to History Chart.
4. Create a new chart by selecting New Chart followed by the chart’s range. The options are: - Last Minute - Last Hour - Past Working Day (6am to 8pm) - Last 24 Hours - Last Week - Last Month - Last Year - Chart Range - User Defined
5. The chart appears in Active Dashboards.
6. If your Active Dashboards window is not open, navigate to View and select Active Dashboards.

Note

You must have at least version 4.8.0. of both Active Console and Gateway

Troubleshooting Copied

This section highlights some of the common problems or configuration errors encountered when connecting Gateway to Gateway Hub.

For more information about administrating Gateway Hub and troubleshooting errors, see Troubleshooting in Gateway Hub.

Specifying the REST address Copied

You can specify the REST address of the Gateway Hub you want to connect to using the Gateway Setup Editor, or by using the -gateway-hub option when starting the Gateway from the command line.

If an address is specified using the command line this will take precedence over any address specified in the Gateway Setup Editor. You must specify the REST address from the command line to use central configuration or anomaly detection.

The Gateway expects a REST address of the form https://<hostname>:<port> only. Addresses containing trailing slashes or using non-standard syntax will be considered invalid.

Disabling the connection to Gateway Hub Copied

After you have started publishing data to Gateway Hub, be aware that temporarily disabling this connection may result in Gateway Hub containing references to obsolete or deleted items. For example, if a managed entity is deleted, the Gateway cannot buffer this information and the Gateway Hub is not notified of the deletion when publishing is resumed. It is recommend that, once started, you do not disable publishing from the Gateway to Gateway Hub.

Shared Gateways Copied

Gateway Hub publishing is not available from shared Gateways. Instead, you must enable publishing from the source Gateways. For more information see Gateway Sharing User Guide.

Kafka listener location Copied

When Gateway attempts to connect to Gateway Hub, you may encounter a Kafka error similar to the following:

If the broker address shown in the error message differs from the publishing address, this may indicate that Gateway Hub is configured so that Kafka can only communicate within the Gateway Hub cluster. To resolve this issue please ensure the advertised listeners setting for the Kafka brokers is set to an address accessible to your Gateway.