Gateway Setup Files

Overview

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

File location

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

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 the schema. This schema is distributed with both Gateway 2 and ActiveConsole 2 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

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/>
<expressReports/>
<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:

gateway — Root node of the XML document. All the XML for the gateway configuration is placed within this node. The attributes on the gateway node shown in the example above include the path to the XML schema, which is used by schema-aware editors.
Note: The Gateway refuses to load the setup if either the compatibility attribute or the format of the version number is incorrect.

includes — The includes section contains a list of included setup files, which the gateway will combine to form the configuration it will use. See File merging.
probes — The probes section contains the Netprobe processes gateway will connect to for monitoring. See Probes.
managedEntities — The managedEntities section contains the Managed Entities which will be run on Netprobes. See Managed Entities and Managed Entity Groups.
types —The types section contains details of samplers to load for Managed Entities of a particular type. See Types.
samplers —The samplers section contains details on which samplers will run and what they will monitor. See Samplers.
samplerIncludes — The sampler includes section allows common subsets of sampler settings to be defined as templates. See Sampler includes.
actions — The actions section describes user-provided scripts and executables which will be launched in response to configured events with the gateway. See Actions.
effects — The effects section describes defined routines that can be performed by the gateway. Effects are called by Actions and Alerts but are always run in the context of the specific data-item which caused the event. For more information, see Effects.
commands — The commands section allows users to configure commands which can be run on demand from ActiveConsole or the REST API. See Gateway Commands.
scheduledCommands — The scheduledCommands section allows the scheduling of commands defined in the command section, which will then be run automatically by Gateway. See Scheduled Commands.
rules — The rules section contains user-defined rules in a script-like language. Rules allow users to flag certain conditions of the data being monitored as requiring attention, and are the primary mechanism for triggering other events such as actions. See Rules.
alerting — The alerting section contains a hierarchy of effects that can be triggered by severity changes. See Alerting.
activeTimes — The activeTimes section contains user-defined time periods. These time periods can be referenced by other parts of the configuration, and used to provide time-based control of gateway functions. See Active Times.
dataSets — The dataSets section allows configuration of time series used by Breach predictor. See Data Sets (Time series) .
hotStandby — The hotStandby section allows configuration of the Hot Standby gateway functionality, which ensures monitoring is not interrupted as a result of a failure on the gateway host. See Hot Standby.
databaseLogging — The databaseLogging section describes monitored data to be logged to a database. See Database Logging.
tickerEventLogger — The tickerEventLogger section allows configuration of persistence for gateway ticker events. See Ticker Event Logger.
authentication — The authentication section controls which users can login to the gateway, and what actions they can perform once connected. See Gateway Authentication Technical Reference.
environments — The environments section contains environment variables used in sampler configurations. See User Variables and Environments.
auditOutputs — The auditOutputs section allows configuration of the auditing functionality of gateway. See Auditing.
knowledgeBase — The knowledgeBase section is used to configure data-items with links to web-pages containing knowledge articles (possibly hosted by an external content management system). These articles can then provide a more in-depth description of what is being monitored. See Knowledge base.
persistence — The persistence section contains configuration for storing persistence data, which is used by the historical analysis functions in rules. See Persistence.
staticVars — The staticVars section stores complex data to be used across multiple samplers e.g. FKM tables and process descriptors. See Static Variables.
expressReports — The expressReports section stores allows the users to define a set of predefined reports that can be generated and viewed. See the Express Reports Server documentation.
restrictedSections — The restrictedSections section allows the user to define which other sections can be used in this setup file. It allows an include file to be limited to prescribed functions. See Restricted Sections.
selfAnnouncingProbes — The selfAnnouncingProbes section is used to configure the self-announcing probes feature. See Self-Announcing Netprobes Technical Reference.
exportedData — The exportedData section lists sets of data that the gateway makes available to export to another gateway. See Exported Data.
importedData — The importedData section is used to configure the sets of data that the gateway will import from another gateway. See This section details of all connections to the exporting Gateways. .
publishing — The publishing section allows configuration of the publishing of data from Geneos to other systems. See Publish to Kafka.
gatewayHub — The gatewayHub section allows configuration of publishing data from Geneos to Gateway Hub. See Publishing Technical Reference.
operatingEnvironment — The operatingEnvironment section contains configuration of gateway-wide settings. See Operating Environment.

File merging

Introduction

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

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

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

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

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.

ref-guide6

It is possible to override these within a nested group.

ref-guide7

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.

ref-guide8

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:

Remote setups are cached as per the Gateway's caching scheme.
Should the setup be unreachable the gateway will attempt to fall back to the last cached version.
The cURL library should be present on the Gateway's library search path. Not all configuration options will be supported if it is not and there may be some performance issues as a result.

Common configuration options are described in Remote Include Files.

Examples

Merging different departments gatewaysetup files with a global set of rules

Creating the global rules

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.

ref-guide11

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.

ref-guide12

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

Creating the department gateway setupfile

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:

Hardware
Network

Types:

Hardware Type, which references the samplers Hardware and Network

Probes:

aSolarisMachine
aLinuxMachine
aWindowsMachine

Managed Entities:

aSolarisManagedEntity that references the probe aSolarisMachine and the type Hardware Type.
aLinuxManagedEntity that references the probe aLinuxMachine and the type Hardware Type.
aWindowsManagedEntity that references the probe aWindowsMachine and the type Hardware Type.

Includes:

Priority set to 1.

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

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

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

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.

ref-guide13

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

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

Includes top-level section

includes

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

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). The priority is specified as an integer value in the range 1 to (2³¹ -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

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

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

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

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

includes > includeGroup

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

includes > includeGroup > name

The name of the include group.

Mandatory: Yes

Include group - Advanced tab

includes > includeGroup > remote

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:

http://setup.mydomain.com/include.xml

https://mydomain.com:2345/setups/include.xml

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

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

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

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

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

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

Mandatory: No

includes > includeGroup > remote > authentication > password > password

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

This option specifies the password in un-encrypted format.

Mandatory: No

includes > includeGroup > remote > authentication > password > std

This option specifies the password using std encryption.

Mandatory: No

includes > includeGroup > remote > authentication > password > stdAES

This option specifies the password using AES 256 encryption.

See Secure Passwords.

Mandatory: No

includes > includeGroup > remote > authentication > password > method

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

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

This option is used to explicitly disable proxy server.

Mandatory: No

Default: No proxy server

includes > includeGroup > remote > proxy > proxyServer

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

Mandatory: No

includes > includeGroup > remote > proxy > proxyServer > host

This setting specifies the hostname for the proxy server.

Mandatory: Yes

includes > includeGroup > remote > proxy > proxyServer > port

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

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

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

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

Mandatory: No

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

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

Mandatory: No

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

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

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

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

Mandatory: No

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

This option specifies the proxy server password using std encryption.

Mandatory: No

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

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

See Secure Passwords.

Mandatory: No

includes > includeGroup > remote > timeout

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

includes > include

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

includes > include > priority

Controls the importance of a specific includes file while merging.

includes > include > required

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

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.

includes > include > reloadInterval

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

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

includes > include > remote

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:

http://setup.mydomain.com/include.xml
https://mydomain.com:2345/setups/include.xml

Mandatory: No

includes > include > remote > certificateVerification

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.

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

Mandatory: No

Default: none

includes > include > remote > authentication

Mandatory: No

Default: No authentication

includes > include > remote > authentication > none

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

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

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

Mandatory: No

includes > include > remote > authentication > password > password

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

This option specifies the password in un-encrypted format.

Mandatory: No

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

This option specifies the password using std encryption.

Mandatory: No

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

This option specifies the password using AES 256 encryption.

See Secure Passwords.

Mandatory: No

includes > include > remote > authentication > password > method

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

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

This option is used to explicitly disable proxy server.

Mandatory: No

Default: No proxy server

includes > include > remote > proxy > proxyServer

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

Mandatory: No

includes > include > remote > proxy > proxyServer > host

This setting specifies the hostname for the proxy server.

Mandatory: Yes

includes > include > remote > proxy > proxyServer > port

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

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

Mandatory: No

Default: None

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

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

Mandatory: No

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

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

Mandatory: No

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

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

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

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

Mandatory: No

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

This option specifies the proxy server password using std encryption.

Mandatory: No

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

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

See Secure Passwords.

Mandatory: No

includes > include > remote > timeout

								Mandatory: No
							
								Units: Seconds
							
								Default: 0 (no timeout)

Detailed Configuration for Remote Include Files

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.

ref-guide160

Connecting to the host and file retrieval

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.
						
http://setup.mydomain.com/include.xml
https://mydomain.com:2345/setups/include.xml

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

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

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

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.

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

Check that the realm of the web server is defined with the corresponding names of the kdc, admin server and default domain.
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

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

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

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

SIGUSR1

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

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

Rule 1: All setup sections are merged recursively if they do not have the attribute name or ref e.g.

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

Exception 1: Unless the setup section has to be overridden i.e. tickerEventLogger e.g.

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.

Rule 2: All setup sections are overridden if they do have an attribute name or ref e.g.

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.

Exception 2: Unless they are a special case i.e. a section that is a group type (managedEntityGroup, probeGroup, samplerGroup and ruleGroup)

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

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>