Gateway Setup Files

Overview Copied

The Gateway reads its configuration from the Gateway setup file at start-up. The gateway setup file is formatted as an XML document, as described by the XML 1.0 specification.

Operation Copied

File location Copied

The Gateway reads its configuration from the Gateway setup file at start-up, and also in response to a Reload command.

By default, the Gateway searches its current working directory for a file named gateway.setup.xml, which is then loaded.

Gateway can also be configured to look for a different setup file, using the -setup flag. This flag is followed by the setup filename, for example:

gateway2 -setup /home/Geneos/setups/config1.xml

File format Copied

The Gateway setup file is formatted as an XML document, as described by the XML 1.0 specification . This format is both strict and extensible, and was chosen to allow for validation of the configuration.

The contents of a valid XML document can be described by a set of rules called a configuration schema. This schema is distributed with both Gateway and Active Console and can be used by any schema‑aware XML editor to ensure that the setup file is well-formed XML, and that the contents are valid.

A minimal gateway setup file template (gateway.setup.xml.tmpl) is supplied with the gateway, as well as an example with reasonable initial default settings (gateway.setup.withdefaults.xml.tmpl). Both these files require the addition of a name for the gateway to make them valid; either can be used as a starting point for a full configuration.

If you are editing the setup file without using the Gateway Setup Editor, you can request the gateway to validate a setup file, which will cause gateway to run, print out all the configuration problems it finds and then exit.

gateway2 -setup mySetup.xml -validate

The results of the validation can be generated in JSON format:

gateway2 -setup mySetup.xml -validate-json-output mySetup-validation.json

File contents Copied

The setup file contains many XML elements, which are contained within the top-level gateway element. Each element within the gateway element typically controls a feature of gateway, many of which may work in tandem with each other. These elements are termed top-level sections, and are summarised below.

<?xml version="1.0" encoding="iso-8859-1"?>
<gateway compatibility="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/GA4.0.0-170109/gateway.xsd">
<includes/>
<probes/>
<managedEntities/>
<types/>
<samplers/>
<samplerIncludes/>
<actions/>
<effects/>
<commands/>
<scheduledCommands/>
<rules/>
<alerting/>
<activeTimes/>
<dataSets/>
<hotStandby/>
<databaseLogging/>
<tickerEventLogger/>
<authentication/>
<environments/>
<auditOutputs/>
<knowledgeBase/>
<persistence/>
<staticVars/>
<restrictedSections/>
<selfAnnouncingProbes/>
<exportedData/>
<importedData/>
<publishing/>
<operatingEnvironment/>
</gateway>

Each section of the setup is described in detail in the rest of this document. In brief, the purpose of each of the elements shown above is as follows:

File merging Copied

Introduction Copied

The gateway setup file provides a mechanism for separating out parts of the gateway configuration using include sections. This is useful for sharing common configuration details between different gateways e.g. a local gateway setup (“Main Setup File”) may include a global set of users, rules, activetimes etc. (“Include Setup File”). An example of how this could be organised is shown below.

ref-guide3

Configuration Copied

Merged files are configured within the Includes top-level section of the gateway setup. Configuration consists of a priority for the gateway setup file and a list of include definitions that specify what files to include, if they are required and what priority they should have.

Priorities Copied

A priority is used to resolve any conflicts that can occur when merging a set of setup files e.g. if 2 setup files contain the same setup section the gateway will choose the section that belongs to the setup file with the highest priority. Each setup file must have a priority and that priority must be unique so the gateway can always resolve merging conflicts. The highest priority is specified as 1 with all numbers after e.g. 2, 3, 4 etc. have an increasingly lower priority.

Nested Includes Copied

Nested includes are not supported. A setup validation error is produced if the gateway setup includes setup files that have their own include sections.

Remote Include Files Copied

The Gateway provides a mechanism for accessing remote, read-only included setup files from a remote location via HTTP and HTTPS protocols.

To make configuration more flexible include file groups allow you to specify authentication and connection details common to a group of files in one place. All of the files within the group default to these details.

It is possible to override these within a nested group.

In the screenshot above a new group has been added which inherits the settings from the preceding group but changes the authentication details for the testing environment.

Include files themselves may specify all or none of the detail choosing to inherit from a parent group. The location setting for the include file should be the full URL to the include file.

The screenshots above show the actual include file being configured. Using the information contained in the parent group and the location configured above the file will be retrieved from the configured URL using the team proxy server and production environment credentials.

Points to note:

Common configuration options are described in Remote Include Files.

Examples Copied

Merging different departments gatewaysetup files with a global set of rules Copied

Creating the global rules Copied

Create a new gateway setup file using the gateway setup editor; this setup file will contain all of our global rules. The setup file needs to have a new rule group called “Hardware Rules” which contains 2 rules called “CPU Overloaded” and “Network Overloaded”. .

Next the target and rule need to be set for “CPU Overloaded”. Click on the edit button and make the path selection dialog contain the following with “Filter on selected elements” ticked:

Element Attribute Value
Sampler Type Hardware Type
Sampler Name Hardware
row Name cpuUtilisation
cell Column Value

The rule needs to be set to the following:

if value > 90 then
severity critical
;elseif value > 80 then
severity warning
else
severity ok
endif

The screenshot shows what the setup editor should look like after making these changes.

The “Network Overloaded” rule follows the same setup as the “CPU Overloaded”. The target needs to be set to the following with “Filter on selected elements” ticked:

Element Attribute Value
sampler Type Hardware Type
sampler Name Network
cell Column percentSendErrors

The rule needs to be set to the following:

if value <> 0 then
severity critical
else
severity ok
endif

The screenshot below shows what the setup editor should look like after making these changes.

The global rules setup file is now complete and needs to be saved as “global.rules.setup.xml”.

Creating the department gateway setupfile Copied

e.g. Equities and fixed income department

Create a new gateway setup file using the gateway setup editor. The setup file needs to have the following configured:

Samplers:

Types:

Probes:

Managed Entities:

Includes:

Included file global.rules.setup.xml with a priority of 2.

Save this file as equities.gateway.setup.xml and save a copy as fixedincome.gateway.setup.xml. These setup files will share the same base configuration for simplicity.

Benefit of merging the files Copied

The equities and fixed income departments now rely on global rules. This means that if the rule for “CPU Overloaded” needed to be changed so that severity is critical when the value reaches 85% instead of 90% it only has to be done in 1 place, this makes maintenance easier.

Adding a rule to the equities setupfile Copied

The equities department want to add a rule for the windows network sampler that is not specified by the global rule due to the columns being named differently. To do this a new rule set needs to be created in the equities.gateway.setup.xml file. This will be called “Windows Rules” and will contain a rule called “Network Overloaded”.

Note

It is possible to have rules with the same name in a gateway setup file as long as they belong to different rule groups.

The target needs to be set to the following with “Filter on selected elements” ticked:

Element Attribute Value
sampler name Network
cell column packetSentErrorRate

The rule needs to be set to the following:

if value unlike "0.00*" then
severity critical
else
severity ok
endif
How merging works Copied

Each setting in the setup file that does not contain a name or reference. E.g. the top-level samplers section will be merged recursively; any settings inside this section will be merged providing they too do not have a name or reference. If there are any settings that cannot be merged the setup file with the highest priority’s setting will be kept. The first exception is the tickerEventLogger section will never be merged. The second exception is that groups used for setup management (e.g. probeGroup, samplerGroup, managedEntityGroup, and ruleGroup elements) will all be merged recursively even though they have a name or reference. Any settings that exist in a lower priority setup file but are not in a higher priority file will be added.

To see the rules with examples for merging please refer to Setup Merging Rules.

The figure below shows what the setup editor should look like after making these changes.

When equities.gateway.setup.xml is now sent to the gateway it will include all of the global rules and the additional rule setup for the windows network sampler.

Overriding a global rule in the fixed incomesetup file Copied

The fixed income department want to override the global rule called “CPU Overloaded” and change the rule to set the severity to warning if the CPU goes over 50%. To do this a new rule group needs to be created in the fixedincome.gateway.seutp.xml. This will be called “Hardware Rules”.

Note

The “Hardware Rules” in the fixed income setup file will overwrite the one in the global rules setup file due to the fixed income setup file having the higher priority.

The “CPU Overloaded” rule can be copied and pasted from the global rules section to the fixed income rules section. In the rule the value 80 would be changed to 50.

When fixedincome.gateway.setup.xml is now send to the gateway it will only include the fixed income rule. This is a problem as the “Network Overloaded” rule is now no longer included because it belonged to the “Hardware Rules” in the global rules setup file. To solve this problem the “Network Overloaded” rule would need to be moved to a separate rule group called “Network Rules” in the global rules setup file.

After making these 2 changes the fixed income setup file will now correctly overwrite the “CPU Overloaded” rule and include the “Network Overloaded” rule from the global rules setup file.

Configuration Copied

Includes top-level section Copied

includes Copied

Only the main setup file can contain an includes top-level section, which specifies all the additional files to be included. This prevents cycles where (for example) setup file A includes file B, which includes file A again.

includes > priority Copied

The priority controls the importance of a file when merging. Sections in a higher priority file will take precedence over sections in a lower priority file (see [File merging]#file-merging)). The priority is specified as an integer value in the range 1 to (231 -1) inclusive, with 1 being the highest priority. This particular priority setting affects the priority of configuration in the main setup file, rather than any included setup files.

includes > reloading Copied

This section controls when a gateway will reload its setup. Normally the gateway does not reload its setup unless a user edits the setup via the Gateway setup editor. This section allows the users to automatically reread the setup or to disable reloading of the setup even when the Gateway setup editor sends an update.

includes > reloading > reloadInterval Copied

The interval time in seconds between each reload of the setup. If this is set then the gateway will attempt to reload the setup after the reload interval. If the file has changed then it will be reloaded.

Mandatory: No

includes > reloading > activeTime Copied

This active time controls the times the gateway setup can be changed. If not set then gateway setup changes are applied when they are detected.

If the active time value is set and the gateway is running outside the active time then the setup will not change.

If the Gateway setup editor is used to change the setup while this active time is inactive then the setup file(s) will be changed on disk but the gateway will keep running using the old setup. If the gateway is then restarted the gateway will keep running using the old setup (which it has stored in its cache).

If the file on disk is changed by another source and the reload interval has been set, the changed file will be ignored while the active time is inactive.

When the active time switches from inactive to active, the files on disk will be checked and a new setup applied if available.

If the gateway reloads a setup due to receiving a SIGUSR1 signal, then the setup will be reloaded from disk, ignoring the activeTime settings.

Mandatory: No

includes > reloading > applyToIncludes Copied

If this is set to true then the active time and the reload interval will be applied to the main setup and any include files otherwise it will only apply to the main setup file.

Mandatory: No

Default: false

Include group - Basic tab Copied

includes > includeGroup Copied

Include groups allow include files to be placed in logical groupings. For remote include files that reside on a webserver, these also allow for the grouping of common server and access settings for the group. These settings may be overridden by a nested group or directly by the include file configuration.

Include group - Basic tab Copied

includes > includeGroup > name Copied

The name of the include group.

Mandatory: Yes

Include group - Advanced tab Copied

includes > includeGroup > remote Copied

This setting is used when accessing remote, read-only include file(s) from a remote location such as webserver via HTTP and HTTPs protocols. The values specified in this section applies to all individual include files within this includeGroup (and its nested includeGroups) unless they choose to override them.

The location setting for the remote include file should be the full URL path to the include file. For example:

Mandatory: No

See Remote Include Files for an explanation of how to retrieve configuration from a webserver. See Detailed Configuration for Remote Include Files for a detailed discussion of the common configuration options for Remote Include files.

includes > includeGroup > remote > certificateVerification Copied

The connection to the remote server can be http (unencrypted) or https (SSL encrypted).When using SSL connections the certificate can also be verified. This setting specified what to check within the certificate.

Setting Description
None Will succeed as long as any certificate is present.
Against authority Checks the certificate to ensure it has been signed by a Certificate Authority (CA) that is trusted, but doesn't check that the hostname matches.
Against authority and hostname Checks that the certificate has been signed by a trusted CA and that the hostname matches

When checking the certificate against a Certificate Authority then a CA Bundle in PEM format must be used. This file specifies the CAs that is to be trusted. If the operating system has not come with a CA or it is out of date then a CA Bundle should be specified.

This can either be constructed (if, for example, you wish to add your own trusted authorities when self-signing) or downloaded. If you wish to generate your own then please search online for ‘Creating a PEM CA bundle’. If you just wish to download an existing one then you can do so from the cURL page describing how to extract CA certificates from Mozilla:

http://curl.haxx.se/docs/caextract.html

Mandatory: No

Default: none

includes > includeGroup > remote > authentication Copied

This setting specifies the credentials that the webserver may require to authenticate users trying to retrieve include files. One can configure the username and password. The password may be encrypted in the setup.

Mandatory: No

Default: No authentication

includes > includeGroup > remote > authentication > none Copied

This setting means no authentication is required to access remote include file hosted on a webserver.

Mandatory: No

Default: No authentication

includes > includeGroup > remote > authentication > password Copied

This section specifies the username and password one would require to access remote include file hosted on a secured webserver.

Mandatory: No

includes > includeGroup > remote > authentication > password > username Copied

The username with which one can access the remote include file.

Mandatory: No

includes > includeGroup > remote > authentication > password > password Copied

The password configuration allows gateway to specify the password with which it can access the remote include files.

Mandatory: No

includes > includeGroup > remote > authentication > password > plaintext Copied

This option specifies the password in un-encrypted format.

Mandatory: No

includes > includeGroup > remote > authentication > password > std Copied

This option specifies the password using std encryption.

Mandatory: No

includes > includeGroup > remote > authentication > password > stdAES Copied

This option specifies the password using AES 256 encryption.

See Secure Passwords.

Mandatory: No

includes > includeGroup > remote > authentication > password > method Copied

Allows Basic and GSS-Negotiate (Kerberos) HTTP authentication methods to be selected.

Both methods are enabled by default, but is recommended that you select only one method to speed up the request.

Kerberos authentication requires -kerberos-principal and -kerberos-keytab to be set using the command line. See Gateway command line options in Gateway Installation Guide.

Note

Kerberos authentication is only available on Linux systems.

Mandatory: No

Default: Both methods are enabled.

includes > includeGroup > remote > proxy Copied

This option specifies the settings of a proxy server, that a request to access remote include file, might have to pass through.

Mandatory: No

Default: No proxy server

includes > includeGroup > remote > proxy > none Copied

This option is used to explicitly disable proxy server.

Mandatory: No

Default: No proxy server

includes > includeGroup > remote > proxy > proxyServer Copied

This setting specifies the proxy server settings to access remote include file.

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > host Copied

This setting specifies the hostname for the proxy server.

Mandatory: Yes

includes > includeGroup > remote > proxy > proxyServer > port Copied

This setting specifies the port the proxy server is listening on.

Mandatory: Yes

Default: 80 (http) or 443 (https)

includes > includeGroup > remote > proxy > proxyServer > type Copied

The setting specified the type of proxy server to use. Six types are currently supported.

Type Description
HTTP Http 1.1
HTTP 1.0 Http 1.0.
SOCKS 4 Socks 4.
SOCKS 4A Socks 4a.
SOCKS 5 Socks 5 but resolve the hostname locally.
'SOCKS 5 Hostname" Socks 5 and let the proxy resolve the hostname.

Mandatory: Yes

includes > includeGroup > remote > proxy > proxyServer > authentication Copied

This setting specifies the credentials that the proxy server may require to authenticate users trying to retrieve include files. One can configure the username and password. The password may be encrypted in the setup.

Mandatory: No

Default: None

includes > includeGroup > remote > proxy > proxyServer > authentication > none Copied

This setting is used to explicitly disable authentication to proxy server.

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > authentication > password Copied

This section specifies the username and password combinations to be sent to proxy servers.

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > authentication > password > username Copied

The username with which one can access the remote include file using the proxy server.

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > authentication > password > password Copied

The password configuration allows gateway to specify the password with which it can access the remote include files using the proxy server.

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > authentication > password > password > plaintext Copied

This option specifies the proxy server password in un-encrypted format.

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > authentication > password > password > std Copied

This option specifies the proxy server password using std encryption.

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > authentication > password > password > stdAES Copied

This option specifies the proxy server password using AES 256 encryption.

See Secure Passwords.

Mandatory: No

includes > includeGroup > remote > timeout Copied

Fetching the remote include file may take too long due to demands on the server or network traffic. This setting allows you specify in seconds how long the Gateway should wait for the transfer to complete.

Mandatory: No

Units: Seconds

Default: 0 (no timeout)

Include - Basic tab Copied

includes > include Copied

The includes section can contain any number of include elements, each of which specifies a single file to include.

includes > include > priority Copied

Controls the importance of a specific includes file while merging.

includes > include > required Copied

Marks an included setup file as being required or not. This is a Boolean value and should be set to either true or false. If an included setup file is inaccessible for some reason, this setting then controls gateway behaviour. For files which are required (this setting is set to true) the gateway will not apply the setup if the file is inaccessible. Non-required files which are inaccessible will generate a warning, but gateway will continue to load and apply the setup.

includes > include > location Copied

Specifies the location of the file to include. This should be specified in the form of a file URL (i.e. file://<pathtofile>) and can be specified as either an absolute or relative path. Relative paths are relative to the location of the main setup file.

For remote include files the path should always be the full URL from which to retrieve the file.

See Remote Include Files for an explanation of how to retrieve configuration from a webserver. See Detailed Configuration for Remote Include Files for a detailed discussion of the common configuration options for Remote Include files.

includes > include > reloadInterval Copied

The interval time in seconds between each reload of this include file. This overrides the setting in the includes > reloading section if applyToIncludes has been set to true.

Mandatory: No

includes > include > activeTime Copied

Specifies an active time to apply when using checking this include file for changes. This overrides the setting in the includes > reloading section if applyToIncludes has been set to true.

Mandatory: No

Include - Advanced tab Copied

includes > include > remote Copied

This setting is used when accessing remote, read-only include file(s) from a remote location such as webserver via HTTP and HTTPs protocols. The values specified in this section will override any values specified in the ancestor includeGroups.

The location setting for the remote include file should be the full URL path to the include file. For example:

Mandatory: No

See Remote Include Files for an explanation of how to retrieve configuration from a webserver. See Detailed Configuration for Remote Include Files for a detailed discussion of the common configuration options for Remote Include files.

includes > include > remote > certificateVerification Copied

The connection to the remote server can be http (unencrypted) or https (SSL encrypted).When using SSL connections the certificate can also be verified. This setting specified what to check within the certificate.

Setting Description
None Will succeed as long as any certificate is present.
Against authority Checks the certificate to ensure it has been signed by a Certificate Authority (CA) that is trusted, but doesn't check that the hostname matches.
Against authority and hostname Checks that the certificate has been signed by a trusted CA and that the hostname matches.

When checking the certificate against a Certificate Authority then a CA Bundle in PEM format must be used. This file specifies the CAs that is to be trusted. If the operating system has not come with a CA or it is out of date then a CA Bundle should be specified.

This can either be constructed (if, for example, you wish to add your own trusted authorities when self-signing) or downloaded. If you wish to generate your own then please search online for ‘Creating a PEM CA bundle’. If you just wish to download an existing one then you can do so from the cURL page describing how to extract CA certificates from Mozilla:

http://curl.haxx.se/docs/caextract.html

Mandatory: No

Default: none

includes > include > remote > authentication Copied

This setting specifies the credentials that the webserver may require to authenticate users trying to retrieve include files. One can configure the username and password. The password may be encrypted in the setup.

Mandatory: No

Default: No authentication

includes > include > remote > authentication > none Copied

This setting means no authentication is required to access remote include file hosted on a webserver.

Mandatory: No

Default: No authentication

includes > include > remote > authentication > password Copied

This section specifies the username and password one would require to access remote include file hosted on a secured webserver.

Mandatory: No

includes > include > remote > authentication > password > username Copied

The username with which one can access the remote include file.

Mandatory: No

includes > include > remote > authentication > password > password Copied

The password configuration allows gateway to specify the password with which it can access the remote include files.

Mandatory: No

includes > include > remote > authentication > password > plaintext Copied

This option specifies the password in un-encrypted format.

Mandatory: No

includes > include > remote > authentication > password > plaintext > std Copied

This option specifies the password using std encryption.

Mandatory: No

includes > include > remote > authentication > password > plaintext > stdAES Copied

This option specifies the password using AES 256 encryption.

See Secure Passwords.

Mandatory: No

includes > include > remote > authentication > password > method Copied

Allows Basic and GSS-Negotiate (Kerberos) HTTP authentication methods to be selected.

Both methods are enabled by default, but is recommended that you select only one method to speed up the request.

Kerberos authentication requires -kerberos-principal and -kerberos-keytab to be set using the command line. See Gateway command line options in Gateway Installation Guide.

Note

Kerberos authentication is only available on Linux systems.

Mandatory: No

Default: Both methods are enabled.

includes > include > remote > proxy Copied

This option specifies the settings of a proxy server, that a request to access remote include file, might have to pass through.

Mandatory: No

Default: No proxy server

includes > include > remote > proxy > none Copied

This option is used to explicitly disable proxy server.

Mandatory: No

Default: No proxy server

includes > include > remote > proxy > proxyServer Copied

This setting specifies the proxy server settings to access remote include file.

Mandatory: No

includes > include > remote > proxy > proxyServer > host Copied

This setting specifies the hostname for the proxy server.

Mandatory: Yes

includes > include > remote > proxy > proxyServer > port Copied

This setting specifies the port the proxy server is listening on.

Mandatory: Yes

Default: 80 (http) or 443 (https)

includes > include > remote > proxy > proxyServer > type Copied

The setting specified the type of proxy server to use. Six types are currently supported.

Type Description
HTTP Http 1.1
HTTP 1.0 Http 1.0.
SOCKS 4 Socks 4.
SOCKS 4A Socks 4a.
SOCKS 5 Socks 5 but resolve the hostname locally.
SOCKS 5 Hostname Socks 5 and let the proxy resolve the hostname.

Mandatory: Yes

includes > include > remote > proxy > proxyServer > authentication Copied

This setting specifies the credentials that the proxy server may require to authenticate users trying to retrieve include files. One can configure the username and password. The password may be encrypted in the setup.

Mandatory: No

Default: None

includes > include > remote > proxy > proxyServer > authentication > none Copied

This setting is used to explicitly disable authentication to proxy server.

Mandatory: No

includes > include > remote > proxy > proxyServer > authentication > password Copied

This section specifies the username and password combinations to be sent to proxy servers.

Mandatory: No

includes > include > remote > proxy > proxyServer > authentication > password > username Copied

The username with which one can access the remote include file using the proxy server.

Mandatory: No

includes > include > remote > proxy > proxyServer > authentication > password > password Copied

The password configuration allows gateway to specify the password with which it can access the remote include files using the proxy server.

Mandatory: No

includes > include > remote > proxy > proxyServer > authentication > password > password > plaintext Copied

This option specifies the proxy server password in un-encrypted format.

Mandatory: No

includes > include > remote > proxy > proxyServer > authentication > password > password > std Copied

This option specifies the proxy server password using std encryption.

Mandatory: No

includes > include > remote > proxy > proxyServer > authentication > password > password > stdAES Copied

This option specifies the proxy server password using AES 256 encryption.

See Secure Passwords.

Mandatory: No

includes > include > remote > timeout Copied

Fetching the remote include file may take too long due to demands on the server or network traffic. This setting allows you specify in seconds how long the Gateway should wait for the transfer to complete.

Mandatory: No

Units: Seconds

Default: 0 (no timeout)

Detailed Configuration for Remote Include Files Copied

To retrieve setup from a remote server you need to connect to a host using a particular protocol, possibly authenticate yourself, and there may be a proxy server your request has to pass through. You may also need a way to cancel the operation if file retrieval is taking too long.

The settings to accomplish this are common to Include Groups and individual Include files. The figure below shows an example containing the common settings.

Connecting to the host and file retrieval Copied

The basic settings necessary for using remote include files are the location as a URL, along with a timeout.

Location

This setting is specific to individual include files. The location is the complete URL used to retieve the include file including protocol (http, https) and possibly port. See includes > include for details.

e.g.

Timeout

Fetching the file may take too long due to demands on the server or network traffic for example. This setting allows you specify in seconds how long the Gateway should wait for the transfer to complete.

Authenticating against the HTTP server Copied

The webserver may be configured to authenticate users trying to retrieve files. The authentication section of the configuration deals with this.

Here you configure the username and password. The password may be encrypted in the setup.

Authentication methods Copied

All supported authentication methods are enabled by default. Kerberos authentication (GSS-Negotiate) requires additional configuration prior to use.

IPv6 with NTLM

In a few cases timeout issues have been seen when using NTLM authentication with some types of IPv6 environments.

If you experience any issues then please contact ITRS support so that we can gather more information to diagnose the root cause.

Authenticating with Kerberos Copied

Before setting the Gateway to use Kerberos authentication to connect to a web server, the client machine must first acquire a Kerberos ticket-granting ticket from that web server. The following guidelines describe how to acquire the ticket on a Linux client machine with support for Kerberos. The Gateway currently supports Kerberos authentication on this platform only.

  1. Verify that the Kerberos realm of the web server is defined in the Kerberos configuration of the client. The configuration file is in /etc/krb5.conf. Below is an example of the realms section of the configuration file:

    ...
[realms]
EXAMPLE.COM = {
kdc = kerberos.example.com:88
admin_server = kerberos.example.com:749
default_domain = example.com
}
...

  2. Check that the realm of the web server is defined with the corresponding names of the kdc, admin server and default domain.

  3. Generate the Kerberos ticket-granting ticket for an authorized user and store it in the default location. This can be done by running kinit <user@realm> on the command line. Enter the password when prompted.

    For example:

    kinit User@EXAMPLE.COM

  4. Run klist on the command line to view the generated ticket. Verify that ticket is stored in the default location, i.e. /tmp/krb5cc_0.

    klist

The ticket has a finite lifetime and the client machine needs to regenerate it once it expires. The lifetime of a ticket is controlled by the Kerberos Key Distribution Center (KDC) of the web server, which issues the tickets. The default expiration is typically set to 8 or 10 hours, but can be configured to a longer duration in the KDC. Ticket renewal polices can also be set between the web server and client.

Consult your web server administrator on how to configure Kerberos the ticket lifetime and renewal.

Configuring a Proxy server Copied

The default proxy configuration is “none”. That is it’s assumed that there is no proxy server. If you need to configure a proxy server you should populate the following fields.

Host

This is the machine on which the proxy server is running. It can be specified as an IP-address or server name. The default value if not configured is “localhost”.

Port

The port on which the proxy server is listening for connections, if not set this is defaulted to port 80.

Type

Six types of proxy server are supported.

Proxy Server Version Type
HTTP Http 1.1.
HTTP 1.0 Http 1.0.
SOCKS 4 Socks 4.
SOCKS 4A Socks 4a.
SOCKS 5 Socks 5 but resolve the hostname locally.
SOCKS 5 Hostname Socks 5 and let the proxy resolve the hostname.

Authentication

The authentication section for the Proxy Server matches that of the HTTP Server.

Viewing Remote Include files from the Setup Editor Copied

The Gateway Setup Editor allows you to view remote include files. Remote files cannot be saved, and will therefore be loaded read-only to prevent editing.

The GSE downloads remote include files via the Gateway. This means that it’s not necessary for the files to be visible from the machines running the GSE, but does mean that the main setup file needs to have been loaded via a Gateway (rather than the main setup file being a local file) and that the relevant Gateway connection is up.

Remote include files were introduced in version 3.0.10, and the Gateway must be that version or newer. If an include file is behind a proxy server, or is protected with authentication, then the GSE must also have been upgraded to this version as it needs to provide additional information to the Gateway. If the remote include can be accessed by the Gateway without using these advanced features, then an older GSE may be used to view the remote include files.

Signal Handling Copied

SIGUSR1 Copied

SIGUSR1 is a user defined POSIX reliable signal which is used by the Gateway to reload the Gateway Setup Files. When the gateway receives this signal it will reload its setup. This reload will occur if the files are unchanged and if the reloading time is in an inactive period. This is useful when a user wants to update the gateway setup file while updating the gateway setup file is restricted through GSE includes > reloading > activeTime option.

To deliver this signal, one can issue the following command from the command prompt:

kill -USR1 <gateway_PID>

SIGUSR2 Copied

SIGUSR2 is a user defined POSIX reliable signal which was historically used by the Gateway to run memory leak checks using purify. This has been discontinued and this signal is not intercepted anymore.

Setup Merging Rules Copied 

Main Setup file priority 1 (highest priority)

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<includes>
<priority>1</priority>
<include>
<priority>2</priority>
<required>true</required>
<location>probes.setup.xml</location>
</include>
</includes>

<probes>
<probe name="windows">
<hostname>aWindowsMachine</hostname>
<port>9001</port>
</probe>
</probes>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

Included Setup file priority 2 (lowest priority)

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<probes>
<probe name="solaris">
<hostname>aSolarisMachine</hostname>
<port>9000</port>
</probe>
</probes>
</gateway>

Merged Setup file

<?xml version="1.0" encoding="iso-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<probes>
<probe name="windows">
<hostname>aWindowsMachine</hostname>
<port>9001</port>
</probe>
<probe name="solaris">
<hostname>aSolarisMachine</hostname>
<port>9000</port>
</probe>
</probes>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

The merged setup shows that the sections gateway and probe have been merged. The probe section now contains “windows” and “Solaris”.

Main Setup file priority 1 (highest priority)

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<includes>
<priority>1</priority>
<include>
<priority>2</priority>
<required>true</required>
<location>ticker.setup.xml</location>
</include>
</includes>

<tickerEventLogger>
<maxEvents>25</maxEvents>
<cacheFileSize>55</cacheFileSize>
<cachePaths>
<cachePath>./resources/tickereventloggerA.cache</cachePath>
<cachePath>./resources/tickereventloggerB.cache</cachePath>
</cachePaths>
</tickerEventLogger>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

Included Setup file priority 2 (lowest priority)

<?xml version="1.0" encoding="iso-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<tickerEventLogger>
<maxEvents>30</maxEvents>
<cacheFileSize>55</cacheFileSize>
<cachePaths>
<cachePath>./resources/tickereventlogger1.cache</cachePath>
<cachePath>./resources/tickereventlogger2.cache</cachePath>
</cachePaths>
</tickerEventLogger>
</gateway>

Merged Setup file

<?xml version="1.0" encoding="iso-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<tickerEventLogger>
<maxEvents>25</maxEvents>
<cacheFileSize>55</cacheFileSize>
<cachePaths>
<cachePath>./resources/tickereventloggerA.cache</cachePath>
<cachePath>./resources/tickereventloggerB.cache</cachePath>
</cachePaths>
</tickerEventLogger>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

The merged setup shows that only one tickerEventLogger section is present, this is because the main setup file has the highest priority.

Main Setup file priority 1 (highest priority)

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<includes>
<priority>1</priority>
<include>
<priority>2</priority>
<required>true</required>
<location>probes.setup.xml</location>
</include>
</includes>

<probes>
<probe name="windows">
<hostname>aWindowsMachine</hostname>
<port>9001</port>
</probe>
</probes>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

Included Setup file priority 2 (lowest priority)

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<probes>
<probe name="solaris">
<hostname>aSolarisMachine</hostname>
<port>9000</port>
</probe>
<probe name="windows">
<hostname>anotherWindowsMachine</hostname>
<port>9500</port>
</probe>
</probes>
</gateway>

Merged Setup file

<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<probes>
<probe name="windows">
<hostname>aWindowsMachine</hostname>
<port>9001</port>
</probe>
<probe name="solaris">
<hostname>aSolarisMachine</hostname>
<port>9000</port>
</probe>
</probes>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

The merged setup shows that there is only one probe section named “windows”. The probe section “windows” in the included setup file has been overridden; this is because the main setup has the highest priority.

Main Setup file priority 1 (highest priority)

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<includes>
<priority>1</priority>
<include>
<priority>2</priority>
<required>true</required>
<location>groups.setup.xml</location>
</include>
</includes>

<probes>
<probe name="windows">
<hostname>aWindowsMachine</hostname>
<port>9002</port>
</probe>
<probe name="solaris">
<hostname>aSolarisMachine</hostname>
<port>9003</port>
</probe>
</probes>

<managedEntities>
<managedEntityGroup name="Department 1">
<managedEntity name="ME1">
<probe ref="windows"/>
</managedEntity>
<managedEntityGroup name="Sub Department 1">
<managedEntity name="ME2">
<probe ref="windows"/>
</managedEntity>
</managedEntityGroup>
</managedEntityGroup>
<managedEntityGroup name="Department 2">
<managedEntity name="ME3">
<probe ref="solaris"/>
</managedEntity>
</managedEntityGroup>
</managedEntities>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

Included Setup file priority 2 (lowest priority)

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<probes>
<probe name="aix">
<hostname>anAixMachine</hostname>
<port>9001</port>
</probe>
<probe name="linux">
<hostname>aLinuxMachine</hostname>
<port>9000</port>
</probe>
</probes>

<managedEntities>
<managedEntityGroup name="Department 1">
<managedEntity name="ME5">
<probe ref="aix"/>
</managedEntity>
<managedEntityGroup name="Sub Department 1">
<managedEntity name="ME2">
<probe ref="linux"/>
</managedEntity>
</managedEntityGroup>
<managedEntityGroup name="Sub Department 2">
<managedEntity name="ME7">
<probe ref="aix"/>
</managedEntity>
</managedEntityGroup>
</managedEntityGroup>
<managedEntityGroup name="Department 2">
<managedEntity name="ME8">
<probe ref="linux"/>
</managedEntity>
</managedEntityGroup>
</managedEntities>
</gateway>

Merged Setup file

<?xml version="1.0" encoding="iso-8859-1"?>
<gateway xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=".\resources\schema\gateway.xsd">
<includes>
<priority>1</priority>
<include>
<priority>2</priority>
<required>true</required>
<location>groups.setup.xml</location>
</include>
</includes>

<probes>
<probe name="windows">
<hostname>aWindowsMachine</hostname>
<port>9002</port>
</probe>
<probe name="solaris">
<hostname>aSolarisMachine</hostname>
<port>9003</port>
</probe>
<probe name="linux">
<hostname>aLinuxMachine</hostname>
<port>9000</port>
</probe>
<probe name="aix">
<hostname>anAixMachine</hostname>
<port>9001</port>
</probe>
</probes>

<managedEntities>
<managedEntityGroup name="Department 1">
<managedEntity name="ME1">
<probe ref="windows"/>
</managedEntity>
<managedEntityGroup name="Sub Department 1">
<managedEntity name="ME2">
<probe ref="windows"/>
</managedEntity>
</managedEntityGroup>
<managedEntityGroup name="Sub Department 2">
<managedEntity name="ME7">
<probe ref="aix"/>
</managedEntity>
</managedEntityGroup>
<managedEntity name="ME5">
<probe ref="aix"/>
</managedEntity>
</managedEntityGroup>
<managedEntityGroup name="Department 2">
<managedEntity name="ME3">
<probe ref="solaris"/>
</managedEntity>
<managedEntity name="ME8">
<probe ref="linux"/>
</managedEntity>
</managedEntityGroup>
</managedEntities>

<operatingEnvironment>
<gatewayId>100</gatewayId>
<gatewayName>A Gateway</gatewayName>
<listenPort>8500</listenPort>
</operatingEnvironment>
</gateway>

The merged setup shows that “Department 1” and “Department 2” have been merged. “ME5” has been added to “Department 1”. “Sub Department 2” contains “ME2” from the main setup file as it has overridden “ME2” in the included setup file and lastly “ME8” has been added to “Sub Department 2”.

Merged Setup Example Copied

Assume the gateway main file has contents:

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway compatibility="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/RAmaster-140930/gateway.xsd">
<includes>
<priority>1</priority>
<include>
<priority>2</priority>
<required>true</required>
<location>inc1.example.setup.xml</location>
</include>
<include>
<priority>3</priority>
<required>true</required>
<location>inc2.example.setup.xml</location>
</include>
</includes>
<probes>
<virtualProbe name="vp1"/>
</probes>
<managedEntities>
<managedEntityGroup name="meG">
<managedEntity name="me1">
<probe ref="p1"/>
<sampler ref="cpu"/>
</managedEntity>
</managedEntityGroup>
</managedEntities>
<samplers>
<samplerGroup name="SamplerGroup">
<sampler name="FKM2">
<plugin>
<fkm>
<isPCREMode>
<data>true</data>
</isPCREMode>
</fkm>
</plugin>
</sampler>
</samplerGroup>
</samplers>
<tickerEventLogger>
<maxEvents>8</maxEvents>
<cacheFileSize>8</cacheFileSize>
</tickerEventLogger>
<operatingEnvironment>
<gatewayName>testGateway</gatewayName>
<listenPort>7039</listenPort>
</operatingEnvironment>
</gateway>

And include file inc1.example.setup.xml has contents:

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway compatibility="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/RAmaster-140930/gateway.xsd">
<probes>
<probe name="p1">
<hostname>127.0.0.21</hostname>
</probe>
<probe name="p2">
<hostname>127.0.0.22</hostname>
</probe>
</probes>
<managedEntities>
<managedEntity name="me1">
<probe ref="p1"/>
<sampler ref="FKM"/>
</managedEntity>
<managedEntity name="me2">
<probe ref="p2"/>
<sampler ref="cpu"/>
</managedEntity>
</managedEntities>
<samplers>
<sampler name="FKM">
<plugin>
<fkm/>
</plugin>
</sampler>
<sampler name="cpu">
<plugin>
<cpu/>
</plugin>
</sampler>
</samplers>
<tickerEventLogger>
<maxEvents>1</maxEvents>
<cacheFileSize>1</cacheFileSize>
</tickerEventLogger>
</gateway>

And include file inc2.example.setup.xml has contents:

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway compatibility="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/RAmaster-140930/gateway.xsd">
<probes>
<probe name="p1">
<hostname>127.0.0.23</hostname>
</probe>
</probes>
<managedEntities>
<managedEntityGroup name="meG">
<managedEntity name="me1">
<probe ref="p1"/>
<sampler ref="processes"/>
</managedEntity>
</managedEntityGroup>
</managedEntities>
<samplers>
<samplerGroup name="SamplerGroup">
<sampler name="processes">
<plugin>
<processes/>
</plugin>
</sampler>
</samplerGroup>
</samplers>
<operatingEnvironment>
<gatewayName/>
<httpConnectionRequirements>
<internalData>
<acceptHosts>
<all/>
</acceptHosts>
</internalData>
</httpConnectionRequirements>
</operatingEnvironment>
</gateway>

Then the merged setup will look like:

<?xml version="1.0" encoding="ISO-8859-1"?>
<gateway compatibility="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/RAmaster-140930/gateway.xsd" main="true">
<includes main="true">
<priority>1</priority>
<include>
<priority>2</priority>
<required>true</required>
<location>inc1.example.setup.xml</location>
</include>
<include>
<priority>3</priority>
<required>true</required>
<location>inc2.example.setup.xml</location>
</include>
</includes>
<probes main="true">
<virtualProbe name="vp1" main="true"/>
<probe name="p2" include="inc1.example.setup.xml">
<hostname>127.0.0.22</hostname>
</probe>
<probe name="p1" include="inc1.example.setup.xml">
<hostname>127.0.0.21</hostname>
</probe>
</probes>
<managedEntities main="true">
<managedEntityGroup name="meG" main="true">
<managedEntity name="me1" main="true">
<probe ref="p1"/>
<sampler ref="cpu"/>
</managedEntity>
</managedEntityGroup>
<managedEntity name="me2" include="inc1.example.setup.xml">
<probe ref="p2"/>
<sampler ref="cpu"/>
</managedEntity>
<managedEntity name="me1" include="inc1.example.setup.xml">
<probe ref="p1"/>
<sampler ref="FKM"/>
</managedEntity>
</managedEntities>
<samplers main="true">
<samplerGroup name="SamplerGroup" main="true">
<sampler name="FKM2" main="true">
<plugin>
<fkm>
<isPCREMode>
<data>true</data>
</isPCREMode>
</fkm>
</plugin>
</sampler>
<sampler name="processes" include="inc2.example.setup.xml">
<plugin>
<processes/>
</plugin>
</sampler>
</samplerGroup>
<sampler name="cpu" include="inc1.example.setup.xml">
<plugin>
<cpu/>
</plugin>
</sampler>
<sampler name="FKM" include="inc1.example.setup.xml">
<plugin>
<fkm/>
</plugin>
</sampler>
</samplers>
<tickerEventLogger main="true">
<maxEvents>8</maxEvents>
<cacheFileSize>8</cacheFileSize>
</tickerEventLogger>
<operatingEnvironment main="true">
<gatewayName main="true">testGateway</gatewayName>
<listenPort main="true">7039</listenPort>
<httpConnectionRequirements include="inc2.example.setup.xml">
<internalData>
<acceptHosts>
<all/>
</acceptHosts>
</internalData>
</httpConnectionRequirements>
</operatingEnvironment>
</gateway>
["Geneos"] ["Geneos > Gateway"] ["Technical Reference"]

Was this topic helpful?