If you are currently using version 5.x.x, we advise you to upgrade to the latest version before the EOL date. You can find the latest documentation here.
Auditing
The auditing feature of gateway allows logging of user interactions with the gateway. These logs allow historical tracking of gateway functions and can be used to reconstruct a sequence of events or for security planning.
Auditing works best in conjunction with a configured authentication section. If no authentication is used, then users connecting to gateway will be assigned incrementing usernames "ActiveConsole1", "ActiveConsole2" and so on. Authentication forces the user to login with their username, making it easier to determine which user has performed which actions.
Audit information
The following events are recorded by the gateway's auditing feature:
- User log-on and log-off events (this includes connections from Webslinger, Open Access server and Importing Gateways)
- Logon failure due to rejected authentication (not logons which fail due to inability to establish a connection)
- Command execution, where the command has been executed interactively (not as a scheduled command) and is run on the gateway or a probe (run location not set to 'Client').
- REST interface requests, whether to execute a command or to list available commands.
- Failed command execution, where the command has been executed interactively via the gateway.
- Gateway setup change events, including failed setup change requests
- Gateway start/stop events
Each record contains the following information:
Audit record ID
A globally unique identifier for the audit record, used to link it to any extended autit information (see next section).
Datetime
Time (to nearest second) when the audited action occurred using the local time on the Gateway, in ISO 8601 basic format.
Audit event
The type of action audited. For example "Execute command", "Login".
Username
Username of the user who performed the action.
Workstation IP
IP address the user is connecting from.
Command
Name of the command run (if any). For example "/SNOOZE:manualAllMe".
Fail reason
If the action failed, a brief reason for the failure. For example "Rest Service not enabled on insecure connections", "No permission".
Data item path
Unique path to the data-item the command was run against (if any).
Target Managed Entity
The managed entity associated with the action (if any).
Arguments
Arguments supplied by the user or system when executing a command; the file name of a setup file which is changed; or the comment supplied when setup is applied.
Module
The Gateway component which generated the record. For example, "UserManager", "CommandManager", "RestService".
Gateway name
The name of the gateway which generated the record.
Extended audit information
Certain auditable actions can lead to additional audit details being recorded with reference to that event. Currently this is done for commands executed on dataviews produced by certain plug-ins.
The types of commands that result in extended audit details and the exact information collected would depend on the plug-in. The individual reference guides of plug-ins that return extended audit details explain what details are recorded.
Format
The collected audit details have a generic format in the form of one or more tuples. Each tuple gives the value of a named field for a named "item" related to the particular auditable event. What constitutes an item depends on the component that is providing the audit details.
For example, consider an FKM sampler where a command that affects two triggers is executed. In this case information regarding these two triggers is provided by FKM as audit details. For each trigger, the associated message and input file line are sent as values. In the audit details format, each trigger is represented as a separate "item" and the message and file line for each trigger is represented as a field-value pair associated with that item. E.g.:
| Item | Field | Value |
|---|---|---|
| myfile.log#warning12 | message | Overflow |
| myfile.log#warning12 | line | 10:30:20 Warning: possible overflow…. |
| myfile.log#warning14 | message | Overflow |
| myfile.log#warning14 | line | 10:30:25 Warning: overflow…. |
Note: The above example may not represent the actual information that FKM returns as extended audit details.
The collection of extended audit details is enabled using the collectExtendedDetails setting. By default, it is not enabled.
Limits
In the case of commands, audit details are not be collected for commands that apply above the dataview level. For example, if a command is executed against a managed entity, audit details are not queried and collected from the various dataview that come under that managed entity.
Linking to Main Audit Record
In each of the audit outputs the main audit records are written independently of audit details records (for example, if the database audit output is being used they are written to separate database tables.)
In order to be able to match an audit details record to its main audit record, each auditable event has a unique id. The same audit record id is written as part of any corresponding audit details records.
Data Volume
Depending on the auditable event in question the volume of information gathered as extended audit details has the potential to be high. For example accepting all files on an FKM dataview that is currently displaying a large number of triggers could lead to a correspondingly large amount of audit details that will be written to the configured audit outputs. This should be considered when deciding whether to enable this feature.
Audit Configuration
Audits logs can be written to three different locations; to the gateway database, to file using a flat format or to file using an XML format (see Audit File Format). Output can be written to several locations simultaneously and also to multiple files using the same format if required.
Audit logging configuration is placed in the
auditOutputs top-level section.
This section contains a list of auditOutput settings, each of which
specifies a single location to place the audit log
entry. These locations can be any of the four as listed
above.
Note: Since the database used for audit-logging is the gateway database multiple outputs to the database will generate a setup validation warning.
The settings for audit logging are described below:
auditOutputs
The auditOutputs top-level section contains the configuration for the audit logging feature. This section can contain any number of auditOutput configuration sections.
auditOutputs > collectExtendedDetails
Turning this on will result in the gateway collecting extended audit details when certain auditable actions are invoked. See Extended Audit Details.
auditOutputs > auditOutput
Each audit output section contains the configuration for a single location, to which every audit event in the gateway will be sent. The configuration must contain exactly one of the database, xmlFile or flatFile sections described below.
auditOutputs > auditOutput > database
Specifies that audit information should be written to the gateway database. This section contains no database connection details, since database logging is configured in the database top-level section (see Database Loggin).
auditOutputs > auditOutput > database > maxDescriptionLength
Specifies the maximum length of the description field in the audit_table, where audit data is logged to. The gateway will automatically truncate descriptions which are too long to this length, to ensure that they are logged.
Clients should only need to change this setting if they have extended the description field length above the default length in the database schema provided with gateway.
auditOutputs > auditOutput > xmlfile
Writes audit information to the specified file, using XML formatting.
auditOutputs > auditOutput > xmlfile > filename
Specifies the file to log to. This can be an absolute path, or a relative path (from the gateway working directory).
auditOutputs > auditOutput > xmlfile > maxSizeKb
Optional setting to control the maximum size of
the audit log file, measured in KB. This should be a
non-negative integer value. When the file grows
beyond this size, it is renamed to <filename>.old (deleting
any previous file with this name) and a new file is
created.
auditOutputs > auditOutput > xmlfile > archiveScript
Optional script that is run when the log
file rolls over (when it exceeds the maximum size).
The script is passed <filename>.old as the first
argument, and can then perform any actions on this
file as required.
auditOutputs > auditOutput > flatFile
Writes audit information to the specified file, with one line per entry.
auditOutputs > auditOutput > flatFile > maxSizeKb
Optional setting to control the maximum size of
the audit log file, measured in KB. This should be a
non-negative integer value. When the file grows
beyond this size, it is renamed to <filename>.old (deleting
any previous file with this name) and a new file is
created.
auditOutputs > auditOutput > flatFile > archiveScript
Optional script that is run when the log
file rolls over (when it exceeds the maximum size).
The script is passed <filename>.old as the first
argument, and can then perform any actions on this
file as required.
Basic Configuration
The following shows how to configure an audit output in a flat file called "audit.log", with a rollover size of 102400 kb for the log file and a script to run after the log file has been rolled over.
- Select the Audit Outputs node in the Navigation tree. This results in the auditOutputs pane being displayed as the main pane.
- Select the "Add New" button to create a new audit output instance. A row should appear in the main pane, with a default type of "database" as the value of its first field.
- Change the type from "database" to "flatFile". This causes a "Flat file…" to appear as the second entry in the row.
- Select the "Flat file…" entry. This should result in a dialog box being displayed with options to further configure the audit output instance.
- Specify a name for the flatFile, the maximum size and a suitable archive script. Then select OK. This should result in the same view as depicted for step 4.
Audit File Format
Audit records can be written to file in one of the two formats described below. This section only describes the formats - for the meaning of each of the fields in audit records and extended audit records, please see the sections Audit information and Extended audit information.
XML Format
The root element for the document is <auditRecords> and under this each auditable event is written as a single <auditRecord> element. For example:
<?xml version="1.0" encoding="iso-8859-1"?>
<auditRecords>
<auditRecord>
<auditRecordId>2af649a6-a162-4e6a-911e-7667b55a5925</auditRecordId>
<time>20161109T101346</time>
<auditEvent>Setup file change</auditEvent>
<username>ActiveConsole1</username>
<workstation>192.168.141.1</workstation>
<arguments>
<argument>
<name>File</name>
<value>gateway.setup.xml</value>
</argument>
</arguments>
<module>SetupManager</module>
<gateway>AuditTest</gateway>
</auditRecord>
</auditRecords>
If the extended audit details mode is enabled, then when any auditable event produces extended details these are written as an <auditDetails> element again under the top level <auditRecords> element.
The <auditDetails> element can be tied back to the <auditRecord> element that represents the auditable event using the <auditRecordId> field which is a unique identifier representing the particular auditable event.
E.g.:
<?xml version="1.0" encoding="ISO-8859-1"?>
<auditRecords>
<auditRecord>
<auditRecordId>0be51672-7d67-4f39-b6ca-6f46befe4ee4</auditRecordId>
<datetime>20161109T135926</datetime>
<auditEvent>Execute command</auditEvent>
<username>ActiveConsole2</username>
<workstation>127.0.0.1</workstation>
<command>/PLUGIN:FKM:acceptFile</command>
<dataItem>/geneos/gateway[(@name="AuditTest")]/directory/probe[(@name="p")]/managedEntity[(@name="m")]/sampler[(@name="fkm")][(@type="")]/dataview[(@name="fkm")]/rows/row[(@name="fkm.log")]/cell[(@column="status")]</dataItem>
<targetManagedEntity>m</targetManagedEntity>
<arguments>
<argument>
<name>Arg_0</name>
<value>fkm.log</value>
</argument>
</arguments>
<module>CommandManager</module>
<gateway>AuditTest</gateway>
</auditRecord>
<auditDetails>
<auditRecordId>0be51672-7d67-4f39-b6ca-6f46befe4ee4</auditRecordId>
<auditDetail>
<item>fkm.log#warning00000</item>
<field>message</field>
<value>uhoh</value>
</auditDetail>
<auditDetail>
<item>fkm.log#warning00000</item>
<field>line</field>
<value>warning This is a warning.</value>
</auditDetail>
<auditDetail>
<item>fkm.log#warning00001</item>
<field>message</field>
<value>uhoh</value>
</auditDetail>
<auditDetail>
<item>fkm.log#warning00001</item>
<field>line</field>
<value>warning This is a warning too.</value>
</auditDetail>
</auditDetails>
</auditRecords>
Flat Format
In the flat format audit information is written as comma-separated values. Each line in the file represents either an audit record or a single item of audit detail. To distinguish between these two types of lines, the first item in the line is the string RECORD or DETAIL.
Each audit record representing a single auditable event is written as follows:
RECORD,<audit record id>,<datetime>,<username>,<workstation>,<module>,<managed entity name>,<description>,<gateway name>
E.g.:
RECORD,7592a7a4-17d2-44e5-96a8-9b17d78b9af7,Wed Nov 9 14:03:43 2016,ActiveConsole1,192.168.141.1,SetupManager,,Setup file change File:gateway.setup.xml,AuditTest
RECORD,95eb18f1-55a4-4093-a6a7-4e9872499beb,Wed Nov 9 14:03:43 2016,Administrators,192.168.142.1,SetupManager,,New Setup Applied,AuditTest
Note that the 'description' field combines information from the <auditEvent>,<command>,<failReason>,<dataItem> and <arguments> elements of the XML format.
If the extended audit details mode is enabled then, when any auditable event produces extended details, these are written as one or more audit detail lines. An audit detail line has the following format:
DETAIL,<audit record id>,<item>,<field>,<value>
Audit detail lines can be tied back to the main audit record using the audit record id which is a unique identifier representing the particular auditable event.
E.g.:
RECORD,2b1d5715-8ad4-4b30-b10a-0aad685a8286,Tue Jan 21 11:36:19 2014,ActiveConsole2,127.0.0.1,CommandManager,m,/PLUGIN:FKM:acceptFile DataItem:/geneos/gateway[(@name="AuditTest")]/directory/probe[(@name="p")]/managedEntity[(@name="m")]/sampler[(@name="fkm")][(@type="")]/dataview[(@name="fkm")]/rows/row[(@name="fkm.log")]/cell[(@column="status")] Arg_0:fkm.log,AuditTest
DETAIL,2b1d5715-8ad4-4b30-b10a-0aad685a8286,fkm.log#warning00000,message,uhoh
DETAIL,2b1d5715-8ad4-4b30-b10a-0aad685a8286,fkm.log#warning00000,line,warning This is a warning.
DETAIL,2b1d5715-8ad4-4b30-b10a-0aad685a8286,fkm.log#warning00001,message,uhoh
DETAIL,2b1d5715-8ad4-4b30-b10a-0aad685a8286,fkm.log#warning00001,line,warning This is a warning too.
Gateway Hooks
Overview
Gateway hooks provide a way for clients to fire custom programs or scripts when certain important gateway events occur. We call these programs hooks as they are hooked in to the gateway process. The hooks that are provided interact with the way that the gateway manages its setup. They provide the ability to link to Version Control Systems (VCS) and to provide extra validation of the setup based upon business rules. There are two gateway hooks;
- Validate-setup: This hook is fired during the gateway validation process. The hook can generate extra validation issues, that the gateway will merge with any internally generated issues. These will then either be sent back to the Gateway Setup Editor or printed to the Gateway log, dependent on the reason that the gateway triggered the validation step.
- Post-setup-apply: This hook is fired after the gateway has finished applying a new setup. Information about the setup files used to run the gateway together with information about the change that has occurred are provided to the hook. The expected use of this hook is to pass the files to a VCS. The hook can also pass back to the gateway version numbers for the setup files in use.
Setup
The hooks are all located in a single hooks directory and have pre-defined names. The location of the hooks directory is set at gateway start up by use of the -hooks-dir command line option. The names of the two hook files are "validate-setup" and "post-setup-apply". If the hook file is not present or the hook directory has not been defined, then the hook will not be fired by the gateway. So if the user runs the gateway with the following command;
gateway2.linux -hooks-dir /opt/geneos/gw/hooks
The gateway will look for the following 2 hook files;
- /opt/geneos/gw/hooks/validate-setup
- /opt/geneos/gw/hooks/post-setup-apply
If a relative path to the hooks directory is provided, that is relative to the working directory of the gateway.
Validate-Setup
If the gateway has a hooks directory defined and the file "validate-setup" is present in the directory then the hook will be fired every time the gateway attempts to validate a setup. On completion this hook provides a list (which can of course be empty) of validation issues to the gateway. These validation issues merged with the issues generated by the gateway. They are then reported to back to the user via the log file or the Setup Editor.
Example
The key use of a validate-setup hook is to add business validation on top of the application validation provided by the gateway. In the resources directory you will find an example validate-setup hook. It is located in resources/hooks/examples/validate-setup. This is a python script that will apply the following extra rules to the setup;
An error issue will be raised for each FKM plugin that is created where the isPCREMode flag has not been set to true. A critical issue will be raised if the httpConnectionRequirements has been set in any way If this script is used then setting httpConnectionRequirements will cause the gateway to add a Critical issue to the Setup Validation Issues list. The gateway will not run a setup that has such an issue, so the setup will not be applied if this xml tag is added using the GSE. If the setup is edited by hand to have this issue and then the gateway started it will refuse to start.
If an FKM plugin is created and no other settings are added then, validating the setup will return an error in the GSE. Saving the setup will create a FKM sampler unless the -max-severity command line parameter set to a none or warn. See the Gateway Command Line options section for more details on this parameter.
Note: The issues created by the hook, when seen in the GSE can be clicked upon to take the setup editor to the errant item, just as any other validation issue.
Triggering the hook
The validate-setup hook will be triggered at the following times;
- Gateway start up
- Validation request sent from the Gateway Setup editor to the gateway
- Setup saved from the Gateway Setup editor to the gateway
- Reload of setup due to defined Gateway Reload intervals
- Reload of setup due to gateway receiving a USR1 signal
- Setup tested using the -validate command line option
Data passed to the hook
The validate-setup hook is passed one piece of information, the location of a temporary file containing the setup of the gateway, using the _SETUP environment variable. This file contains a single piece of XML which is the merged setup that the gateway generates when it combines included setup files into a single XML setup. This is similar to the XML as the user can obtain by running -dump-xml setup command line option. The difference being that the command line option gives the merged setup of the files on disk, while the XML provided to the hook may use XML setup sections from the gateways memory prior to being saved to disk. However, it is not necessary for the hook to understand the origin of the XML. Each setup provided to the hook should be processed in the same way and the results returned back to the gateway.
Note: The merged XML nodes will have
additional attribute to specify which setup file
this node came from. A node coming from main file
will have attribute main="true" whereas a node
coming from include file will have attribute
include="/path/to/include/file/as/specified/in/the/setup".
It is implicit that child nodes not having such
attribute inherit it from their ancestor node. This
attribute can be used to do pre-setup validation
such as assure that all FKM samplers come from a
particular file. For illustration, see Merged Setup Example.
| Environment variable | Information stored | Example |
|---|---|---|
| _SETUP | Location of temporary file containing the merged gateway XML setup | /tmp/setup-2381293891.xml |
| _HOTSTANDBY_STATE | The Gateway state - one of Inactive, Standby, Pending, Active or Inactive (licence denied) | Active |
| _HOTSTANDBY_ROLE | The Gateway role - one of Unknown, Stand Alone, Primary or Secondary | Primary |
| _VALIDATE_TYPE | The setup validation reason - one of Validate, Startup, Save, Rollback, SIGUSR1, Command, Automatic Reload or Licence Change | Startup |
| _COMMENT | The comment entered into the setup editor when the setup was changed. This is always passed as a blank value except on a setup change. |
The following environment variables have a blank value passed on start up and a non-GSE triggered setup change:
| Environment variable | Information stored | Example |
|---|---|---|
| _USER | User who is validating or saving the setup. | admin |
| _WORKSTATION | Host machine name or IP address of the user. | 10.102.103.04 |
| _ROLES | Roles or groups that the user belongs to. | Administrators |
| _USER_AUTHENTICATION_TYPE |
Method used by the user to log in to Geneos. This is one of three values:
|
SSO |
Data passed back by the hook
The hook passes data back to the gateway by printing an XML document to its standard output. This XML document needs to conform to the schema provided in hooks/schema directory (resources/hooks/schema/validate-setup-result.xsd). There is also an example of the output that could be generated in the examples directory (resources/hooks/examples/validate-setup-result.xml) shown below:
<validation>
<issues>
<issue>
<severity>Error</severity>
<path>/gateway/samplers/sampler[2]</path>
<message>Middleware Requirements: FKM must use PCRE</message>
</issue>
<issue>
<severity>Error</severity>
<path>/gateway/samplers/sampler[3]</path>
<message>Middleware Requirements: FKM must use PCRE</message>
</issue>
<issue>
<severity>Critical</severity>
<path>/gateway/operatingEnvironment/httpConnectionRequirements</path>
<message>Middleware Requirements: Access to ORB pages is forbidden!!!!</message>
</issue>
</issues>
</validation>
As can be seen, the XML is simply a list of validation issues. Each issue should contain the following information:
- A Message <message>: A human readable description of the issue. This will be shown to the user in the GSE and printed in the Gateway setup.
- A Severity <severity>: The severity of
the issue being reported. This can take one of the
following values;
- None: This is an information message and does not affect the level of severity of the setup
- Warn: This is a warning message. Adding a message of this type will increase the severity of the setup to Warning if it is not currently warning or greater
- Error: This is a warning message. Adding a message of this type will increase the severity of the setup to Error if it is not currently warning or greater
- Critical: This is a warning message. Adding a message of this type will increase the severity of the setup to Critical if it is not currently warning or greater
- An XPath <path>: This is the XPath to an item in the setup that the issue applies to. This should be an XPath a single data item.
In the above example 3 issues are passed back, 2 samplers have been marked as in error because they are FKM samplers but do not have the isPCREMode set. The third issue is a critical issue cause because an httpConnectionRequirements section has been defined in the setup.
The path to the problem items in the Setup XML is provided.
Note: This path is not the same as the path to the same on the running gateway.
The XPath provided is applied to the merged setup provided by to the hook, so that the gateway can link the issues to the offending items in the setup. This then allows the setup editors using the GSE to select an issue and be taken to the offending item.
The hook does not need to pass data back. If nothing is passed back on the standard output, and the hook terminates with an zero error code. The gateway will treat this as if an XML document had been returned with an empty issues list.
If this hook is present, the gateway requires that is run successfully every time that it is fired. If the hook does not run successfully that the gateway will generate a Critical validation issue and ignore any output from the script. If the failure occurs at start up then the gateway will not start. If the failure occurs when the gateway is attempting to apply a new setup, then the gateway will refuse to apply the new setup and keep running on the existing setup. There are 4 types of failure:
- The hook terminates incorrectly (crash)
- The hook returns a non-zero error code
- The hook fails to terminate in under 2 minutes
- The hook passes back data on the standard output which the gateway cannot parse correctly.
The default timeout of 2 minutes can be changed to a different value using the command line option:
-hooks-timeout
Examples:
gateway2.linux_64... -hooks-timeout 90 #90 second timeout on Gateway validation hooks
gateway2.linux_64... -hooks-timeout 3m #3 minute timeout on Gateway validation hooks
Note: Settings greater than the default of 2 minutes will result in a warning that Gateway performance may be degraded.
Post Setup Apply
If the gateway has a hooks directory defined and the "post-setup-apply" is present then the hook will be run every time the gateway applies a new setup correctly. The script is provided with a list of the setup files used by the gateway. On completion it can pass back a list of version numbers for those files. The version numbers of the currently active files are then printed to the gateway log and updated in the Gateway IncludesData plugin (if configured).
Triggering the hook
The post-setup-apply hook will be triggered every time that the setup is reapplied;
- Gateway start up
- Successful setup save from the Gateway Setup editor
- Successful reload of setup due to defined Gateway Reload intervals
- Successful reload of setup due to gateway receiving a USR1 signal
Data passed to the hook
The gateway passes 4 pieces of information to the post-setup-apply hook. Each stored in an environment variable shown below;
| Environment Variable | Information Stored | Example |
|---|---|---|
| _COMMENT | A comment typed in by the setup editor in the Gateway Setup Editor when the setup was changed | Added new Managed Entity |
| _USER | User name of the setup editor | This is the Genos username as described in Authentication |
| _WORKSTATION | The machine ip address where the Setup was edited | 183.23.23.12 |
| _FILES | An XML Document containing the information about the state of all of the setup files |
<setup>
<files>
<file>
<main/>
<path>gateway.setup.xml</path>
</file>
</files>
</setup>
|
The schema for the _FILES XML block can be located in hooks/schema directory (resources/hooks/schema/post-setup-apply-files.xsd).There is also an example of the output that could be generated in the examples directory (resources/hooks/examples/post-setup-apply-files.xml) shown below;
<setup>
<files>
<file>
<main />
<path>gateway.setup.xml</path>
</file>
<file>
<include>inc1.xml</include>
<path>inc1.xml</path>
<setupPending />
<gseChanged />
</ file>
<file>
<include>http://mwserver/users.xml</include>
<remote />
</file>
</files>
</setup>
The example above shows 3 setup files. The first file is the main file and it is located at gateway.setup.xml (relative to the working directory of the gateway). The lack of an setupPending node indicates that the version of the file on disk is the same as the version being used by the gateway. The second file is an include file that is stored locally on disk. The presence of the setupPending node indicates that the version on disk is being currently ignored by the gateway. Probably because of the use of active times on the include files. The gseChanged node indicates that this hook was fired because the user saved a new setup by saving from the GSE to the gateway and that this file was changed on this occasion. Finally the third file is remote setup file that is downloaded on demand from a web server. No path is provided as it is not saved locally.
Summarizing, for each file the following information is provided;
- name: The include file name is provided in a <include> block. The main file does not have an include block, instead it has a <main> block
- path: This is the path to the file on disk. This path is relative to the working directory of the gateway. That is provided for the main setup file and any local include files. A remote setup file has a tag of <remote> instead of a path.
- user changed: If the file was changed in the gse, then there will be a <gseChanged> tag in the file block.
Note: If a file is changed external to the gateway this tag will not be set.
- pending: There will be a <setupPending> flag in the gateway if the file on disk is not the file that the gateway is currently using.
Data passed back by the hook
The gateway does not wait for the post-setup-apply-hook to terminate. Once it fires the hook, it will return to processing normal data. It will however process the results from the hook when the hook terminates. Because it does not block waiting for the results of the hook, the gateway does not impose any time period on the hook script to finish. When the script does finish, the gateway will process the output. The output from the hook is list of files. Each file has a name and a version. This list is passed as an XML document to standard output by the hook.
This XML document needs to conform to the schema provided in hooks/schema directory (resources/hooks/schema/post-setup-apply-result.xsd). There is also an example of the output that could be generated in the examples directory (resources/hooks/examples/post-setup-apply-result.xml) shown below;
<setup>
<files>
<file>
<path>gateway.setup.xml</path>
<version>35eda74</version>
</file>
<file>
<path>inc1.xml</path>
<version>35eda74</version>
</ file>
<file>
<path>inc2.xml</path>
<version>35eda74</version>
</file>
</files>
</setup>
The version needs be set for each file individually. This allows different include sections to be stored in different VCS repositories. There is no limit on the version returned, the gateway treats this simply as a string. Thus it can be a SVN Revision number or a GIT SHA1 hash.
Note: The path passed back should match the path provided in the _FILES XML section provided to the hook by the gateway.
If there is the hook failure then the results
passed back from the hook will be ignored. There are
3 types of failure:
- The hook terminates incorrectly (crash).
- The hook returns a non-zero error code.
- The hook passes back data on the standard output which the gateway cannot parse correctly.
When the versions are received, the version number of the setups actually being used by the gateway will be saved to the log file and updated in the Gateway-Includes plugin. The version number of pending setups will be cached so that the version will be available when the setup file becomes active.
Debug flags
Following debug options can be turned on in the Operating Environment Advanced section under HooksManager:
When turned on, above options will give more information such as hook is fired and the result returned from respective hooks.
Knowledge base
Organisations may have their own knowledge bases, document repositories, or information scattered across a number of systems. The Geneos Knowledge base functionality allows you to leverage this information without being tied to any particular system.
A Knowledge base article is a document that can be reached through a URL. These can be grouped into sets of related information making them easier to organise and maintain.
To create a knowledge base article:
- Open Gateway Setup Editor.
- In GSE, click Knowledge Base
. A dialog window appears on the screen. - Click Yes to create a new knowledge base.
- Click New KBA set.
- Enter the name for the new KBA set in the Name field.
- Click Add new in the KBA field.
- Provide the necessary information to the following fields:
- Label — name for the knowledge base article.
- URL elements — sets the actual URL where the knowledge base article is linked to.
- Targets — defines the XPath of the element where the knowledge base article should appear in the Active Console.
- Click Save current document
to apply changes. - In the Active Console, right-click the sampler and hover Knowledge Base menu.
In this example, the Knowledge base article is set to appear from managed entity > sampler:
Knowledge Base Configuration
knowledgeBase
A Geneos Knowledge Base is a repository of references to Knowledge Base Articles. Knowledge Base Articles are documents of relevance to target data-items within the Geneos system which can be reached via a URL.
Data-items are things like managed entities, gateways or cells within a metrics view.
knowledgeBase > urlTemplate
Knowledge Base Articles are reached via URLs. A urlTemplate allows this URL to be built up from several parts which are concatenated together in the order in which they are defined to form the complete URL. A URL template can be a combination of literal text, parameters and XPaths to Geneos data-items.
urlTemplate's are named and may be disabled from the configuration.
knowledgeBase > urlTemplate > urlTemplateElements
A URL template can be a combination of literal text, parameters set when the Knowledge Base Article is configured and XPaths to Geneos data-items.
knowledgeBase > urlTemplate > urlTemplateElements > urlTemplateElement
An individual URL template element. A piece of literal text, an XPath or a parameter.
knowledgeBase > urlTemplate > urlTemplateElements > urlTemplateElement > literal
Literal text that forms part of a URL.
knowledgeBase > urlTemplate > urlTemplateElements > urlTemplateElement > xpath
This specifies an XPath to a geneos data-item. For example a managed entity name, a cell in a dataview or the contents of a cell. This will be substituted for the XPath when the URL is resolved. See the XPaths - User Guide for more information.
knowledgeBase > urlTemplate > urlTemplateElements > urlTemplateElement > parameter
This specifies the name of a parameter that will be substituted for a value specified when the Knowledge Base Article URL is configured.
knowledgeBase > kbaSet
A KBA Set is a named collection of Knowledge Base Articles (KBAs).
knowledgeBase > kbaSet > kba
This specifies a Knowledge Base Article (KBA). A KBA definition consists of a label, a number of URL elements and target data-items within a Geneos configuration that the article is applicable to.
knowledgeBase > kbaSet > kba > label
This specifies a label for the Knowledge Base Article. The label will be visible from clients such as Active Console for items on which the article is applicable.
knowledgeBase > kbaSet > kba > urlElements
This specifies a number of elements which together make up a URL to the article.
knowledgeBase > kbaSet > kba > urlElements > urlElement
This is an individual part of a URL. A URL may be made up of one or more of these by concatenating them in the order defined. urlElements are a choice of literal, urlTemplate or xpath.
knowledgeBase > kbaSet > kba > urlElements > urlElement > literal
This is a piece of text defining part of all of a URL.
knowledgeBase > kbaSet > kba > urlElements > urlElement > urlTemplate
This is a reference to a URL template. From here it is possible to give values to named parameters in a URL template.
knowledgeBase > kbaSet > kba > urlElements > urlElement > urlTemplate > parameters
A list of parameters to be substituted with those defined in the referenced urlTemplate.
knowledgeBase > kbaSet > kba > urlElements > urlElement > urlTemplate > parameters > parameter
A name / value pair with the name and value for a urlTemplate parameter.
knowledgeBase > kbaSet > kba > urlElements > urlElement > urlTemplate > parameters > parameter > name
This is the name of the parameter.
knowledgeBase > kbaSet > kba > urlElements > urlElement > urlTemplate > parameters > parameter > value
This is the value to be substituted for the parameter.
knowledgeBase > kbaSet > kba > urlElements > urlElement > xpath
This specifies an XPath to a Geneos data-item. For example a managed entity name, a cell in a dataview or the contents of a cell. This will be substituted for the XPath when the URL is resolved. See the XPaths - User Guide for more information.
Mandatory: Yes
Note: Beginning Geneos 5.5.x, the Managed Entity display name is used in the user readable paths throughout the Gateway Setup Editor, except when the GSE is opened as a standalone application. This only applies if you open the GSE within the Active Console.
knowledgeBase > kbaSet > kba > targets
This is a set of target data-items for which the article is applicable.
knowledgeBase > kbaSet > kba > targets > target
This is an XPath to a Geneos data-item. If this XPath can be resolved to a data-item while the gateway is active the Knowledge Base Article will be available from that target. See the XPaths - User Guide for more information.
knowledgeBase > kbaSet > kba > availableToDescendants
This specifies if an article is available to all children of the target data-item. For example if the target is a managed entity, setting this to true will make the article available to all sampler views and cells within those views.
knowledgeBase > localServer
This setting allows a number of documents to be grouped in a directory on a file system that is reachable by the gateway. All of the files within the directory are eligible as knowledgebase articles.
The gateway will act as a web server to serve
these files. Files can then be retrieved from the
local server through http://<gatewayhost>:<gatewayport>/knowledgeBase/<file>.
e.g.
http://server.company.com:7039/knowledgeBase/default.html
Ticker Event Logger
A ticker event is a notification of something of interest. An example of which is a Netprobe shutting down. Ticker events are reported to the gateway by Geneos components and the gateway publishes them to interested parties such as Active Console.
The Ticker Event Logger maintains a list of historic ticker events which can be logged to a persistent cache.
Ticker Event Logger Configuration
tickerEventLogger > maxEvents
This specifies the maximum number of events to be kept in the Ticker Event Logger list.
tickerEventLogger > cacheFileSize
This specifies the maximum number of records that can be written to a cache file. If this parameter is not enabled, then no cache files will be created, and events will not be saved across a restart.
tickerEventLogger > fireOnComponentStartup
Events may be logged when a gateway or netprobe is first started.
tickerEventLogger > fireOnConfigurationChange
Events may be logged following a change of the gateway configuration file.
tickerEventLogger > fireOnCreateWithOkSeverity
Events may be logged following a dataview item being created and transitioning from undefined to OK severity.
tickerEventLogger > severityChangeEventRestrictions
These settings determine if severity change events should fire a notification.
tickerEventLogger > severityChangeEventRestrictions > snoozing
The snoozing restriction can be used to prevent ticker event notifications firing depending upon the snooze state of the data-item which triggered it. Allowable values are listed below:
| Value | Effect |
|---|---|
| alwaysFire | Always produce notifications of severity changes, regardless of snooze state. |
| fireIfItemNotSnoozed | The notification is fired if the triggering data-item is not snoozed. The snooze state of ancestors (e.g. the Managed Entity) will not have an impact on whether the notification occurs. |
| fireIfItemAndAncestorsNotSnoozed | The notification is fired if the triggering data-item and all of its ancestor data-items are not snoozed. |
Default Ticker Events
By default, following events/conditions create a ticker event:
- Netprobe connecting to a Gateway
- Netprobe disconnecting from a Gateway
- Message broadcasted by Gateway
- Dataview item severity change (excluding severity change from undefined to OK following creation unless fireOnCreateWithOkSeverity is set to true)
- Dataview item deletion (only for those dataview items with severity warning or higher)
- Dataview has duplicate row names and OperatingEnvironment "Duplicate row alerts" set to Ticker_and_status
- Connection to database
- Disconnect from database
- Database logging failure events
- Discarding database log entries due to database logging failure
- Dataview item logging success following previous unsuccessful attempt
- /PLUGIN:PROCESSES Start Process Command is issued
- /PLUGIN:PROCESSES Stop Process Command is issued