Geneos ["Geneos"]
You are currently viewing an older version of the documentation. You can find the latest documentation here.
["Geneos > Gateway"]["Technical Reference"]

Gateway Sharing User Guide

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.

Importing

Below is an example of an imported connection. This defines the connection to an exporting gateway. The configuration provides:

  1. The location of the exporting gateway (host and port)
  2. A list of named data sets to import

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 ignored

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

What is shared

By default, only raw data values are shared, the philosophy being that the importing gateway will be able to treat the imported probes as if they were normal netprobes, applying its own rules, handle its own logging, actions, alerts, snoozing, active state, user-assignment, etc.

The following items are shared by the exporting gateway:

  • The value of cells in dataviews that belong to samplers which match the shared dataset paths.
  • Any computed cell values, and any additional gateway created dataviews, or rows, columns, and headlines on dataviews that belong to samplers which match the shared dataset paths.
  • Gateway Plugins, if they match the shared dataset paths.
  • Virtual Probes, if they match the shared dataset paths.
  • Self-Announced Probes, if they match the shared dataset paths.
  • Runtime Parameters are shared (e.g. the connection state of probes).
  • Configured Parameters are shared (e.g. host and port of probes).
  • Managed Entity Attributes are shared.
  • If importSeverity is set, the severity and active state of components are also shared.

The following items are not shared by the exporting gateway:

  • The Severity of cells and components (unless importSeverity is set).
  • The Active state of cells and components (unless importSeverity is set).
  • The Logged and Logging Success status.
  • The Knowledge Base information of cells and components.
  • The Snooze state of cells and components (unless importSeverityWithSnooze is set).
  • The User Assignment state of cell and components (unless importSeverityWithUserAssignment is set).
  • The configured environments of directory components are not shared.
  • Database logging defined on an exporting gateway will not be available on the importing gateway.
  • Rules defined on an exporting gateway will not be available on the importing gateway.

Limitations of Shared Data

For the most part, shared data can be treated exactly as if it were from a normal Netprobe.

However, there are some important limitations:

  • Additional computed dataviews, rows, columns, and cells cannot be added. This is because there is no place to configure them.

  • If importSeverity is set, then it is not possible to execute rules on the imported data.

  • Unless importSeverityWithSnooze is set, Snooze commands will execute on the local copy of the imported data, not on the exporting Gateway.

  • Unless importSeverityWithUserAssignment is set, User Assignment commands will execute on the local copy of the imported data, not on the exporting Gateway.

  • Commands exported by samplers on imported probes (for example, FKM Clear this Trigger) are available on imported data only if the conditions described in Commands are met.

  • Most other commands, including SampleNow and RMS commands, are not available on imported data.

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.

Publish

If the "Publish" setting is set to false then sampler data is not published to the exporting gateway. Thus it will not be present in the exporting or the importing gateway.

Hide Columns & Hide Rows

These settings hide the rows and columns before the data is published by the data provider. Thus neither the exporting gateway nor the importing gateway will see the hidden columns and rows.

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.

See Import Severity with User Assignment.

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

See importedData > connection > attributes.

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.

Setting Description Mandatory
dataSet

Named subset of monitoring data that the exporting gateway exposes. Each data set can have multiple paths.

No
dataSet > name

Name of the data set that the exporting gateway is exposing. This name will be used by the importing Gateway to request shared data.

Yes
dataSet > paths

List of paths to data that the Gateway will expose. The Gateway will export any sampler, Gateway Plugin, Virtual Probe or Self-Announcing Netprobethat matches one of the specified paths.

Yes
dataSet > restrictedAccessexportedData > dataSet > restrictedAccess

List of user names that are allowed to access the dataset.

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 is also dropped if the setup changes such that the connected user no longer has access to any one of the requested datasets.