Introduction
Gateway sharing can be used to share monitoring data from one Gateway to another. This is achieved by having one Gateway exporting a named subset of its monitoring data and another Gateway importing by requesting that subset by name.
This feature can be used to:
- Apply different sets of rules/actions/alerts/etc to the same data.
- Limit the data visible to certain users.
- Manage configuration better by specialising gateways - for example, a data-gathering Gateway with sampler configuration exporting to a rule-application Gateways.
- To duplicate data to satellite sites where connectivity is poor.
Simple Example
Exporting
Below is an example of an exported data set. It has name (in this case "CPU Sampler") which is to be used by the importing gateway. It also has a set of paths that are used to define the objects to be exported. In this case we are exporting all the samplers on the gateway that have a PluginName of CPU.
Go to Navigation > Exported data in the Gateway Setup Editor.
Imported Data Sets
Data sets are defined by one or more XPaths. The paths can be any number of probes, managed entities, or samplers in the exporting gateway. Paths pointing to dataviews or individual cells are not supported. Also paths that reference run time values (for example severity or connection state) are not supported.
The matching components are shared by the exporting gateway along with all their ancestors and descendants.
If a path points to a specific sampler then the following are shared
- the sampler
- the sampler's managed entity
- the sampler's probe
- all the sampler's dataviews
If a path points to a specific managed entity then the following are shared
- the managed entity
- the managed entity's probe
- all the managed entity's samplers
- all the dataviews on all of the managed entity's samplers
The path expressions used to define the data sets exported by a gateway cannot include any runtime information in their filters. Any path containing such filters will be ignored and an error similar to the one below will be generated.
Cannot use non-identifying predicate: [predicate]. Path will be ignoredMore information about identifying predicates and non-identifying predicates can be found in XPaths - User Guide especially in the section on Predicates.
Conflict Resolution
It is possible for the names of imported components to conflict with components already in the importing gateway. The reason for this conflict is that gateways require that all probes and all managed entities have unique names.
Conflicts are always deemed to apply to entire probes, even if only one of multiple managed entities caused the conflict. Probes and all their exported children are either imported in their entirety or not at all.
In the event of a conflict between a shared probe and a probe configured in the setup file of the importing gateway, the setup file will always win and the shared probe will not be imported. This is true even when a conflict is introduced by a setup change, although a setup validation warning will be issued when saving the setup.
In the event of a conflict between shared probes imported on different connections, it is undefined which probe will win.
Note: If multiple connections are made to the same gateway and they import the same probe, this will be considered a conflict (unless the optional prefix setting is used to remove the conflict).
In the event of a conflict between a shared probe and a self-announced probe, it is undefined which probe will win.
An optional prefix can be applied to the names of all imported probes and managed entities to help resolve conflicts.
When a conflict is resolved, either by configuration changes on the importing or exporting gateway, the probe will be imported once more.
Hot-Standby
The importing gateway, when configured as a Hot Standby pair, will behave the same as any other gateway configured in Hot Standby pair. When the primary importing gateway goes down, the secondary will take over and re-establish the connection with the exporting gateway(s), so the import will work seamlessly in a Hot Standby configuration.
The configuration for importing gateways (as shown earlier in this section) allows an importing connection to be configured with a primary and secondary gateway.
In order to import from an exporting gateway in Hot Standby mode, the user can specify the secondary gateway connection details (host and port). If the port is not specified, it defaults to the default gateway listen port (7039) for both primary and secondary exporting gateway. The importing gateway will always import data from the currently active gateway in the Hot Standby pair. Every time a failover happens, a new connection will be established with the exporting gateway which takes over.
Data Quality
Because imported probes share the same connection they behave differently with regards to data-quality in the following ways:
- The importing connection can be suspended like any other, but if it is all the imported probes for the connection will be marked as suspended.
- If a probe is suspended on the exporting gateway, it will be marked as suspended on the imported gateway but there will be no option to unsuspend it.
- The commands to suspend and unsuspend probes are replaced with commands to suspend and unsuspend the importing connection for imported probes.
Commands
Exporting gateways can export commands as well as data to the importing gateway. When the user executes an imported command on the importing gateway, the importing gateway delegates the execution of the command to the exporting gateway. The exporting gateway executes the command and returns the results to the importing gateway, which in turn returns the results to the user via the Active Console or Web Server.
Hence these commands are referred to as "delegated commands". In order for an exporting gateway to accept a command from an importing gateway, three things need to be true
- Importing gateways connect to the exporting gateway using the `useSslCertificate as authentication` setting
- User connects to the importing gateway using a Single Sign On user
- The command must be a delegated command.
Service Connection
In order for the exporting gateway to allow command delegation, a secure connection needs to be established between the exporting and importing gateway. The exporting gateway requires the user to authenticate themselves using an SSL certificate. This ensures that passwords are not being stored in the importing gateway setup and that the connection is a secure connection.
If the importing gateway uses another form of connection, then delegated commands will be rejected by the exporting gateway. These commands will not be presented to the user if they are running a GA4.5.0 or newer Active Console or Webserver.
SSO Users
In order for the exporting gateway to allow command delegation, the user must authenticate themselves using the Geneos SSO Agent. If the user autheticates themselves using system login or password login to the importing gateway, then when the command request is passed to the exporting gateway it will be rejected. In these circumstances, the imported commands will not be presented to the user if they are running a GA4.5.0 or newer Active Console or Webserver.
Delegatable Commands
There are multiple types of commands in the gateway, below is a list of the commands that can be delegated.
Rule Commands
Currently this set of commands just includes the 'Show Rule' command. This set of commands is only delegated if the user has imported severity data. If the user does not import severity data this set of commands will all be run locally.
Snooze Commands
This is the set of commands that allow a user to snooze a cell, as well as the `Unsnooze` command and the `Snooze Info` command. This set of commands is only delegated if the user has imported snooze data. If the user does not import snooze data this set of commands will all be run locally.
For example:
If a CPU sampler has a rule that turns the cell red at 90% on the exporting gateway and a different rule that turns the cell red at 70% on the importing gateway (which is not importing severity or snooze information). A value of over 90% would result in the cell on the exporting gateway turning red and the cell on the importing gateway turning red. Snoozing the cell on the importing gateway will not snooze the cell on the exporting gateway. Likewise, snoozing the cell on the exporting gateway will not snooze the cell on the importing gateway.
User Assignment Commands
This is the set of commands that allow a user to assign a cell to a user, as well as the `Unassign` command and the `User Assignment Info` command. This set of commands is only delegated if the user has imported user assignment data. If the user does not import snooze data this set of commands will all be run local.
Probe Commands
This is a set of commands defined on probes and managed entities that are executed on the Netprobe. Currently this set just include the 'View Netprobe log' command.
Sampler Commands
This is the set of commands that are defined by the probe samplers. Examples of these commands are;
- "Top 20 Processes" defined by the Hardware sampler
- "Clear this Trigger" defined by the FKM sampler
- "Show Expression Diagnostic" defined by the Webmon sampler
These commands are automatically exported along with the data.
This set of commands does **not** include commands that are defined by gateway samplers.
This set of commands does include the commands that are generated from the probes enviroment. An example of generated commands are the commands that the JMX sampler builds to allow access to the mbean management operations.
Netprobe User Commands
There are 3 run locations for User commands:
- Netprobe
- Gateway
- Client
Only the user commands that run on the Netprobe are exported. These like "Sampler Commands" are automatically exported along with the data.
'Gateway' and 'Client' user commands can be shared by sharing include files. In the case of 'Gateway' user commands, the scripts run will need to be available on the importing gateway server, as the commands will be run on the importing gateway. They will not be delegated to the exporting Gateway.
Further restrictions for Snooze and User Assignment on Probe and Managed Entity targets
A snooze or user assignment command that alters state will not be executed by the exporting Gateway and will instead return an error. If this were to be executed then the effect on such a snooze or user assignment could have implications outside of the exported dataset.
Authentication
By default an importing gateway will use a non-authenticated connection to import data from an exporting gateway. This will suffice as long as the exporting gateway does not enforce authentication. However, even if the exporting gateway does not enforce authentication, it will not allow command delegation on a non-authenticated connection.
To import data from a gateway that does enforce authentication, on the importing gateway the import data configuration must specify authentication details in the form of a username and password which will be used to connect to the exporting gateway. It is recommended that an SSL certificate is used to authenticate the user. It is possible to use a user name and password but this disables the exporting of any commands.
The user login credentials used by the importing gateway are done by populating the optional authentication section in the Advanced tab of the imported data connection which intends to export from that particular export gateway.
User Set-up
On the exporting side, this username must be set up as a user in the authentication section. The user must be allowed to connect and receive gateway directory data. The example below shows the user setup. A summary view has been shown as the user name and description are configured in the basic tab, while the ssl settings are configured in the advanced tab.
For example:
Restrictions
System and PAO authentication is not supported as the importing gateway has no mechanism for such. Effectively to provide secure authentication the user would need to have a password specified.
In all other respects, a user configuration that facilitates a connection from a direct downstream component such as Active Console 2 to view data should allow an importing gateway to connect and import data. There is no way to mark a user as only usable for Gateway Sharing purposes.
Storing Passwords
On the importing side, the password can be stored in the gateway setup file as plain text or encrypted using either Geneos legacy encryption (std) or AES 256-bit.
Authentication Failure
In the case of authentication failure a "login failure" message will be written to the log of both importing and exporting gateways. The importing gateway will not be able to import the specified data sets from particular exporting gateway.
When this occurs the connection status of the connection will be set to rejected in the gateway Imported data plugin (if configured).
If the user credentials used by an importing gateway are changed (password, password type) on the exporting gateway, the gateway will drop all importing connections that use those credentials. This will be reported in the exporting and importing gateway logs. The importing gateway will re-establish the connection if its connection details are still valid, otherwise the user will have to amend the details in the importing gateway in order to reconnect.
The exporting gateway will also drop the connection to an importing gateway if one of the following changes occurs to the user used by the importing gateway:
- the exporting gateway does not support the authentication method proposed by the importing gateway
- data permissions is set to data none permissions (and the gateway is configured to support this)
- the user is deleted
The exporting gateway will also drop the connection to an importing gateway if the authentication -> authenticateUsers flag has changed from enabled to disabled state. This would cause any earlier rejected connections to drop, so that the importing gateway can reconnect.
Restricted Access
Each dataset can be restricted to a set of users who can view them. When a connection is made a check is made to see if access is restricted. If it is then the user is checked against the set of allowed users. If the user does not have access to all of the required datasets then the connection is dropped.
The connection will also be dropped if the set-up changes such that the connected user no longer has access to any one of the requested datasets.
Sampler Visibility Settings and Dataview Additions
Dataview Additions
It is possible to add rows, columns and headlines to a dataviews. These additions are performed on the exporting gateway. The cells created and the values they contain will be visible on both the importing and the exporting gateway.
Sampler Visibility Settings
It is possible to set visibility settings on a sampler. The following sections describe how those settings interact with Gateway Sharing.
Is Visible
If the "Is Visible" setting is set to false then sampler data is not published to any clients. Thus it will be present in the exporting gateway but will not be present in the importing gateway.
Import state information
Import severity
If importSeverity is set to true on a connection, the gateway will import the severity and active state of shared data from the exporting gateway, and will disable local rule evaluation on shared data from the exporting gateway so that the imported severity and active state cannot be overridden. Import-severity cells may still be referenced by rules targeting other cells.
The ShowRules command will be delegated to the exporting gateway. See Gateway Sharing > Commands.
Import severity with snooze
If importSeverityWithSnooze is set to true on a connection, the Gateway imports the snoozed state of shared data from the exporting Gateway. Snooze commands that are run on imported data items are delegated to the exporting Gateway.
See Import Severity with Snooze.
Import severity with user assignment
If importSeverityWithUserAssignment is set to true on a connection, the Gateway imports the userAssigned state of shared data from the exporting Gateway. User assignment commands that are run on imported data items are delegated to the exporting Gateway.
Attributes
It's possible to configure an importing gateway to apply specific attribute values to the managed entities that it imports. These can be specified on a per-connection basis such that the respective attribute values are applied to managed entities imported through each connection.
In the case where an imported managed entity has any of these attributes specified originally, then the original values would be overridden by the values specified in the importing configuration.
E.g.:
Original attributes in imported managed entity:
- Region = LDN
- App = A1
Attributes specified in importing configuration:
- Region = Imported
- Source = SourceX
Resulting attributes in imported managed entity:
- Region = Imported
- App = A1
- Source = SourceX
Allowing dynamic connection to the exporting gateway
The ActiveConsole supports a "Connect to Source Gateway" command for the following Gateway plugins:
- Snooze Data plugin
- UserAssignment Data plugin
- Severity Data plugin
This command allows a user to connect to the exporting gateway without having its connection parmeters configured in their Active Console. By default, the details needed to make this dynamic connection are provided by the exporting gateway, as run-time parameters of the sampler.
In some cases, the hostname and port provided by default, which are determined by the configuration of the exporting gateway, are not useable by the Active Console. For example, the hostname might use an alias not known to the Active Console. To allow dynamic connections in these cases, use the configuration settings documented at importedData > connection > dynamicConnection.
Configuration
Imported Data
This section details of all connections to the exporting Gateways.
A Connection entry is defined per exporting Gateway. Each entry details:
- Gateway host.
- Port.
- Authentication details (if any).
- One or more named data sets that the exporting Gateway exposes.
| Setting | Option | Description | Mandatory | Default |
|---|---|---|---|---|
| Name | Name given to the importing connection with the exporting Gateway. | Yes | ||
| Primary | Gateway host and port for the primary exporting Gateway (in case the exporting Gateway is configured in Hot Standby mode) or the standalone exporting Gateway that this connection connects to. | Yes | ||
| Hostname | Host name for a primary (or standalone) exporting Gateway to establish connection with. | Yes | ||
| Port |
Port for a primary (or standalone) exporting Gateway to establish connection with. |
No | 7039 | |
| Secondary |
Gateway host and port for a secondary exporting Gateway, in case the exporting Gateway is configured in Hot Standby mode. When connecting to an exporting Gateway configured in Stand Alone mode, this setting should not be configured. In case of Hot Standby mode, when either primary or secondary exporting gateway goes down, the connection is re-established with the other exporting gateway when it takes over. |
No | ||
| Hostname |
Host name for a secondary exporting Gateway to establish connection with. |
No | ||
| Port |
Port for a secondary exporting Gateway to establish connection with. |
No | 7039 | |
| Secure | Setting this flag indicates that the Gateway should connect to the exporting Gateway using secure protocol. If the flag is set then the port selected should be the secure port of the exporting Gateway. See Secure Communications for more details. | |||
| Data Sets |
Named subsets of monitoring data to import, as configured on the exporting Gateway. If more than one dataset is specified the union of all datasets will be imported. |
Yes | ||
| Authentication |
Username and password that is needed to establish an authenticated connection to the exporting Gateway. This is necessary where the exporting Gateway enforces authentication. If connecting to an exporting Gateway that does not enforce authentication then this can be left unset. |
No | ||
| Username |
Username to be used for an authentication connection. |
|||
| Password |
Password to be used for an authentication connection. This can be stored as plain text or encrypted using either Geneos legacy encryption (std) or AES 256-bit. See Secure Passwords. |
|||
| UseSSLCertificate |
Setting this option indicates that the Gateway's SSL Certificate will be used to authenticate the connection. |
|||
| Prefix |
An optional name that can be prefixed to the imported probes and managed entities names, to resolve any name conflict with existing probes/managed entities or those imported from other exporting Gateway connection. If this name is mis-specified then an error will be raised by the Gateway and the connection will be ignored. |
No | ||
| Attributes | Attributes to be applied to all managed entities imported through this connection. See Attributes. | No | No attributes specified | |
| Import |
State information that can be imported from the sharing Gateway. |
No | ||
| Import Severity |
Import the severity and active state of cells and components from the sharing gateway. Enabling this will disable local rule evaluation on the imported data. The ShowRules command will be delegated to the sharing gateway. |
No | Not imported | |
| Import Severity with Snooze |
Import the snoozed state of cells and components from the sharing gateway. Snooze commands that are run on imported data items will be delegated to the sharing gateway. |
No | false | |
| Import Severity with User Assignment |
Import the userAssigned state of cells and components from the sharing gateway. User assignment commands that are run on imported data items will be delegated to the sharing gateway. |
No | false | |
| Dynamic Connection | Controls the parameters supplied for Active Console to use when executing the "Connect to Source Gateway" command. | No | Use exported parameters | |
| Use Exported Parameters |
Default option, supplies the hostname and port published by the exporting Gateway. |
|||
| Use Importing Connection | Supplies the same connection parameters to Active Console as are configured for this importing connection. | |||
| Override | Supplies explicit parameters for Active Console to use when connecting to the exporting Gateway. | |||
| Override > Primary > Hostname | Host name used by Active Console when connecting to the primary (or standalone) exporting Gateway. | Yes | ||
| Override > Primary > Port | Port used by Active Console when connecting to the primary (or standalone) exporting Gateway. | No | 7039 | |
| Override > Secondary |
Caution: Only use these settings if the exporting Gateway is configured in Hot Standby mode. |
No | ||
| Override > Secondary > Hostname |
Host name used by Active Console when connecting to the secondary exporting Gateway. Caution: Only use these settings if the exporting Gateway is configured in Hot Standby mode. |
No | ||
| Override > Secondary > Port |
Port used by Active Console when connecting to the secondary exporting Gateway. Caution: Only use these settings if the exporting Gateway is configured in Hot Standby mode. |
No | 7039 |
Exported Data
This section is all the named subsets of monitoring data that the exporting Gateway exposes.