Gateway Hub Quickstart
Overview
You can connect Gateway and Gateway Hub to share data and centralise administration.
You must have at least version
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
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
Connect using the Gateway Setup Editor
To connect a Gateway to Gateway Hub and share data follow these steps:
- Open Active Console.
- Double-click the Gateway you wish to configure with Gateway Hub. This opens the Gateway Setup Editor (GSE).
- In the GSE, double-click Gateway Hub in the Navigation tree. This creates the Gateway Hub section.
- In the Gateway Hub section:
- 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
. - In REST address, add the REST address location of Gateway Hub. The REST address uses HTTPS. The default REST address is
https://<hostname>:8081
.
- 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
- 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.kafka.security.protocol=ssl kafka.ssl.ca.location=<location of CA certificate PEM file>
- Click Validate current document.
- 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 fromhub.pem
you provided when installing Gateway Hub or generated by the installer if nohub.pem
is provided. Thetrust-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
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 using SSO
In order to use Gateway Hub for centralised configuration or to perform anomaly detection, you should connect to the Gateway Hub using Kerberos SSO.
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 for production environments.
To connect to Gateway Hub using SSO:
- Configure SSO in Gateway Hub, see Configure single sign-on (SSO) for more information
- Configure the SSO Agent, see SSO Agent User Guide and Gateway Hub SSO Agent for more information.
- Start the Gateway using the following command-line options:
-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.
For more information, see Centralised Gateways User Guide, Anomaly Detection, and Data Sets (Time series).
Monitor Gateway Hub
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.
View metrics in Active Console
To view historical metrics using data from the Gateway Hub via the Active Console, follow these steps:
- In the Active Console, navigate to a dataview.
- In the dataview, right-click a cell you want to view historical data for.
- Navigate to History Chart.
- 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
- The chart appears in Active Dashboards.
- 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
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
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.
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
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
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
When Gateway attempts to connect to Gateway Hub, you may encounter a Kafka error similar to the following:
GatewayHubPublishing Kafka producer error: Local: Broker transport failure: ssl://localhost:9092/0: Connection refused
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.