Geneos

Gateway Commands

Commands

Overview

Gateway commands are the primary method of interaction between the Gateway and connected users. Commands are invoked by users through a controlling process (such as Active Console) which prompts the Gateway to perform a given operation.

There are several types of command:

  • Internal Gateway commands. These are commands that affect the internal operations of gateway. For instance, the gateway snooze functionality can be controlled by internal commands.
  • Internal Plug-In commands. These commands allow users to affect the operation of a specific plug-in running on a Netprobe process. These have special meanings which are understood by a plug-in and may affect the monitoring data that plug-in produces. E.g. the "View file" command for the FKM plug-in.
  • User commands. These are commands defined by users in the gateway setup, which can run external scripts, executables or shared library functions.
  • Tasks commands allow users to group multiple commands together so they will run sequentially in the order they are defined in the task.

Gateway and Plug-In commands are defined by the Netprobes and Gateways versions that are currently being used in the system. User and Task commands are defined by Geneos administrators so the configuration options described in this section concerns these types.

Common Command Settings

This section describes settings common to both user and task commands.

Names

Commands are defined in the command section as a list of named command nodes. As commands are referenced by name in other parts of the gateway setup, each command must have a unique name among all other command definitions.

Targets

The target of a command defines the set of data-items that the command will run against and are defined using an XPath (see the XPath User Guide for more information on XPaths; in particular, the Commands - Useful Targets section provides examples of their use as command targets). This could be a particular Gateway, ManagedEntity or Netprobe or a set of these. The set of commands that are available on a given data-item are viewable from the right click menu's on that DataItem in ActiveConsole.

Permissions

Command permissions apply to Gateway commands. This includes both internal and user-defined commands, but permissions checks are only performed when a user attempts to execute a command. There are three permission values for command permissions: none, view, execute. A full discussion of permissions can be found in Command permissions in Gateway Authentication.

Displaying Commands

By default a command will be displayed to the user by its unique name. The 'label' setting on a command or command group can be used to override the name that will be presented to the user. For example, the following command configuration (1):

Results in the command being displayed as:

Grouping Commands

Commands can be logically grouped into commandGroups in the setup editor. This can be used to for purely organisational purposes within the setup file or to create sub menus that will be presented to the user.

To create organisational groups, create named commandGroups within the setup editor. Commands can then be created or dragged into these. E.g. Group1, Group2 and Group3 (2):

To enable the command groups to affect the menu system, use the 'menu' and optional 'label settings in the command group. In this example the command group 'Is commands'(3) has the 'menu' option selected and the 'Label' is set to override to the text 'ListCommands':

Note: The parent Group, Group3 has specified the menu option but without the label override, so the label will default to the name of the Group (5).

The examples above would present the following options to the user:

Configuration

User-defined commands are configured inside the commands top-level section. This section contains a list of command nodes, each of which defines a single command. The commands must be uniquely named, and have special meaning as described above.

commands

The command top-level section holds the gateway user-defined command configuration. This section can contain any number of command definitions.

commands > commandGroup

Logically groups a set of commands in the setup editor. This can be used for purely organisational purposes within the setup file or to create sub menus that will be presented to the user.

commands > commandGroup > menu

Causes the commands under the commandGroup to be presented to the user under a sub-menu.

Mandatory: No
Default: (no sub-menu is not created)
commands > commandGroup > menu > label

Defines the name given to sub-menu created for the command group.

Mandatory: No
Default: (the name of the command group)

Commands top-level configuration - Advanced tab

For configuration of the REST service, see REST Configuration.

commands > gseCommands

Presents a drop-down menu that allows you to enable or disable certain GSE commands:

  • enableProposeSchema — enabled by default.

    Note: Propose Schema command in the GSE runs against all instances of the named sampler on the Gateway. This may not be desirable on production a Gateway.

commands > requireSnoozeComments

Specifies that snooze commands require comments to be entered to execute the command. This includes the Unsnooze command.

Comments are logged and/or published to the database if enabled on the Gateway.

This affects commands run from Active Console, through REST, or through Gateway sharing. The enforcement of this depends on the command target and Active Console version:

  • Active Console v4.10.0 and newer enforce the input of comments on commands.
  • Active Console v4.9.0 and older do not enforce the input of comments on commands. Instead, these AC2s pass commands that require comments to the Gateway. The Gateway returns an error if there is no comment included in the command parameters.
  • If the Active Console goes through one Gateway that does not enforce comments, to reach another Gateway that does, the Active Console passes the command to the Gateway. If there is no comment, Gateway returns an error.
Mandatory: No
Default: False
commands > requireUserAssignmentComments

Specifies that user assignment commands require comments to be entered to execute the command. This includes the Unassign command.

Comments are logged and/or published to the database if enabled on the Gateway.

This affects commands run from Active Console, through REST, or through Gateway sharing. The enforcement of this depends on the command target and Active Console version:

  • Active Console v4.10.0 and newer enforce the input of comments on commands.
  • Active Console v4.9.0 and older do not enforce the input of comments on commands. Instead, these AC2s pass commands that require comments to the Gateway. The Gateway returns an error if there is no comment included in the command parameters.
  • If the Active Console goes through one Gateway that does not enforce comments, to reach another Gateway that does, the Active Console passes the command to the Gateway. If there is no comment, Gateway returns an error.
Mandatory: No
Default: False
commands > encodedPassword

Allows you to set a password for user-defined Gateway commands with Enable Password set to true.

The password is encoded using the UNIX crypt command-line utility.

Mandatory: No
Default: Password is not set

Command configuration - Basic tab

commands > command

The command section contains the definition for a single command. Each section must be uniquely named among all other commands, and additionally the command name can form part of the menu structure as seen in Active Console or be overridden by the label flag.

commands > command > name

Specifies the name of the command. This name must be unique within the setup file.

Mandatory: Yes
commands > command > targets

A list of data-items this command will be displayed for. Targets in the list are combined using the Boolean OR operation. i.e. if any items in the list match, the command will be displayed. If the gateway has an imported data section configured then there are some restrictions to the paths that can be used. Please see Commands.

Mandatory: No
Default: Command will not be displayed (can be accessed from a task or action only)
commands > command > targets > target

An XPath name which describes the data-items that this command applies to. See XPaths - User Guide for more information on XPaths; in particular, this section gives some examples of their use as command targets. See also the naming documentation for more information.

Mandatory: No
Default: Command will not be displayed (can be accessed from a task or action only)
commands > command > userCommand

Contains the configuration for a user command. Mutually exclusive with task below.

Mandatory: No
Default: A task is configured.
commands > command > task

Contains the configuration for a task command. Mutually exclusive with userCommand above.

Mandatory: No
Default: A user command is configured.

Command configuration - Advanced tab

commands > command > label

The label is displayed to the user as the entry for this command, in the right-click menu. This should be kept relatively short so that the text can be displayed in a menu, but still describe what the command does to users.

Mandatory: No
Default: Command name is displayed to the user
commands > command > description

Optional short description of the command to explain to what the command is intended for.

Mandatory: No
Default: No description

User Commands

User commands are the simplest form of user defined command. These commands allow users to configure programs to be run by the gateway in response to commands issued from Active Console.

There are two types of user commands; script commands which run a script or executable file, and shared-library commands which run a function inside a shared library. Script commands require at least one argument which specifies the script or executable to run. Shared library commands require two arguments, the first specifying the shared library and the second the function within the shared library to run.

When a command is executed, it is passed a target data-item to execute upon. This data-item will have been previously matched against the target data-items specified in the command (in order to display the menu to the ActiveConsole 2 user). This data-item is used by internal commands to act upon, and can also be referenced by user commands using the xpath argument type as described in Command arguments below.

Configuration of a user command is placed within the userCommand section of a command definition, after the base command configuration described above. The settings for this section are as follows.

An example configuration is shown below:

Command arguments

Commands can be specified with a list of arguments. When a command is executed these arguments are then passed to the script, executable or shared library function during the call.

The first argument must be a static type and specifies the script the command will run. By default Gateway will check it's running directory for available scripts. You must specify an absolute path to use scripts from a another directory.

There are four types of arguments:

  • Static arguments - fixed arguments which do not change.
  • Text arguments - combination of fixed + Geneos variable arguments; the value of which is evaluated based on the execution data-item environment.
  • XPath arguments - evaluated arguments which change based on the execution data-item.
  • User-input arguments - these arguments are provided by the user at execution.

Static arguments are the easiest to configure, as they consist of a simple string. This string will be passed to the command every time it is executed - the value cannot change unless users modify the gateway setup.

Text arguments can be specified as a combination of fixed text and Geneos variables. The Geneos variables values are evaluated according to the execution data-item environment. XPath arguments are specified as an XPath, which is evaluated by the client (e.g. ActiveConsole 2) when the command is executed, without the need for user interaction. The path is evaluated relative to the target data-item the command has been run on, and so is best used to extract the value of the data-item, or other nearby data-items. See XPaths - User Guide for more information on XPaths.

User-input arguments are the most common type of argument as they provide the most flexibility in a command. When a user attempts to execute a command containing user-input arguments, a dialog will appear on the client (e.g. ActiveConsole 2) prompting the user to fill in values for these arguments. This prompt will also describe the argument requested and additionally contain default values which the user can choose to override.

Configuration

commands > command > userCommand > type

The type of the user command. Valid values are script or sharedLibrary.

Mandatory: Yes
commands > command > userCommand > runLocation

The run location describes where the command will be run. Valid values are gateway, netprobe or client. Gateway commands will be run by gateway, while netprobe commands will be run by the Netprobe on which the context variable resides. Netprobe commands can only be specified for a script-type action, due to current limitations in Netprobe. Client commands will execute on the connected client application (ActiveConsole2).

Mandatory: Yes

Example script:

<command name="Run PowerShell Script">
<targets>
	<target>/geneos/gateway[(@name=&quot;MNL_PUGO_GATEWAY_9370&quot;)]/directory/probe[(@name=&quot;LORO_6370&quot;)]/managedEntity[(@name=&quot;LORO&quot;)]</target>
</targets>
<userCommand>
	<type>script</type>
	<runLocation>netprobe</runLocation>
	<args>
		<arg>
		<static>powershell.exe -executionpolicy bypass -file &quot;D:\_tickets\Scripts\hello world.ps1&quot;</static>
		</arg>
	</args>
	<enablePassword>true</enablePassword>
</userCommand>
</command>

Once the script has been setup, you can execute the Run PowerShell Script command in the Active Console.

commands > command > userCommand > args

Command arguments are configured inside the args section of a command, with one arg definition per argument. The contents of an arg definition are described below:

Mandatory: A minimum of one argument is required
commands > command > userCommand > args > arg > concatenate

Optional Boolean setting which controls whether the value of this argument should be concatenated to the previous argument, before being passed to the underlying script or shared‑library. This can be used to build up strings which include variables, similar to using a UNIX shell. E.g. prefix_$(var)_postfix, which would be done using three different arg nodes.

Mandatory: No
Defaults: False
commands > command > userCommand > args > arg > static

A static (fixed) command argument to pass directly to the command. Mutually exclusive to text, xpath or userinput.

Mandatory: No
commands > command > userCommand > args > arg > text

A variable command argument to pass directly to the command. This can include static text or Geneos variables which will be evaluated to their respective values depending upon the target data-item the command is being executed on. Example: if a Geneos variable "OS" is defined with different values at 2 different Managed Entities, and the command is run on both these Managed Entities data-items, then both command instances will get different value of "OS" depending upon the Managed Entity data-item it is being run on. The argument type is singleLineStringVar and can consist of static data and/or any number of Geneos variables interleaved together with/without static data. E.g. "Host:$(OS)-$(VERSION)" where "OS" and "VERSION" are 2 pre-defined Geneos variables. Currently only the following variables values can be properly converted to string:

Variable Type Value
boolean "true" is checked, "false" otherwise
double The actual double value specified
integer The actual integer value specified
externalConfigFile The name of an external configuration file.
macro The value of the macro selected - gateway name or gateway port or managed entity name or probe host or probe name or probe port or sampler name.

Currently, this argument is supported only for commands with run location "Gateway" or "Netprobe". If the user tries to configure a command with "text" argument and run location "client", a setup validation error will occur and the command will be ignored.

The value of an argument may be made up of text and variable references. To make it explicit when secure values are used references to secure passwords are replaced with "XXX" at runtime. Secure values should be passed in the secureEnvironmentVariables section.

Mutually exclusive to static, xpath or userinput.

Mandatory: No
commands > command > userCommand > args > arg > xpath

A XPath name relative to the command execution DataItem, which will be evaluated automatically by the client process (e.g. ActiveConsole 2). This can be used to automatically extract values from the system when the command is run.

Any valid XPath in the system can be used here, however some useful examples for cell commands are summarised here:

XPath Meaning
@column The name of the column for the cell that has been selected.
@value The value of the cell that has been selected.
@rowname The name of the row for the cell that has been selected.
../cell[@column="xxx"] The value of the cell in column xxx on the same row as the cell that has been selected.
ancestor::managedEntity The name of the managedEntity that contains the cell that has been selected.

See XPaths - User Guide for more information on XPaths. This is mutually exclusive to static, text or userinput.

commands > command > userCommand > args > arg > userInput

This defines an argument that must be provided by the user when executing a command. This is mutually exclusive to static or XPath.

The argument restricts user input to that type must be one of the following types:

  • boolean
  • float
  • integer
  • singleLineString
  • multiLineString
  • options
  • timeInSeconds
  • xpathOptions
  • password
commands > command > userCommand > args > arg > userinput > description

A description of the argument. This text is displayed as part of the prompt to the user for the argument value so should describe what the argument means.

Mandatory: Yes
commands > command > userCommand > args > arg > userinput > boolean

Specifies a Boolean argument, and the default argument value. Valid values are true or false.

commands > command > userCommand > args > arg > userinput > float

Specifies a real number (i.e. with numbers after the decimal point), and the default argument value.

commands > command > userCommand > args > arg > userinput > integer

Specifies an integer (whole number) argument, and the default argument value.

commands > command > userCommand > args > arg > userinput > singleLineString

Specifies a text string, and the default argument value. Cannot contain newline characters.

commands > command > userCommand > args > arg > userinput > multiLineString

Specifies a text string and default argument value. Can contain new line characters.

commands > command > userCommand > args > arg > userinput > timeInSeconds

Specifies a time as number of seconds since 01-Jan-1970 00:00:00 UTC (i.e. a Unix timestamp).

Valid values are positive integers (including 0), times cannot be negative.

This is the time shown to the user when the command is run.

The default value is 01-Jan-1970 00:00:00. If the field is left as the default value, the user is shown the current time when the command is run. This option is recommended.

Alternatively, you can use the drop-down option to specify a time. The drop-down option shows a calendar and three buttons:

  • Now — changes the field to the current time.
  • None — empties the field. This resets the time to default.
  • OK — the field changes to the time specified in the calendar.
commands > command > userCommand > args > arg > userinput > xPathOptions

Takes one or more XPaths as configuration.

These XPaths are evaluated on the client and the result of this is presented to you as a multiple choice selection.

The XPath results are presented to you in the same order as the XPath configuration, i.e. the results of the first XPath followed by the second XPath etc. Duplicate entries are removed from the result list.

commands > command > userCommand > args > arg > userinput > password

Prompts the user to enter the password needed to run the target script or library.

The password is AES256-encrypted before it is passed to the target script or library.

You must provide your own key-file when starting the Gateway. The key-file is used to encrypt the password, and therefore it is not possible to decrypt it outside the Gateway if it is encrypted using the Gateway's own key. See Secure Passwords.

commands > command > userCommand > args > arg > userinput > options

Specifies a list of options the user can choose from. There must be at least one option specified. The first option in the options list is the "default option" which is displayed to the user.

commands > command > userCommand > args > arg > userinput > options > option

A user option.

commands > command > userCommand > args > arg > userinput > options > option > label

Optional label which is displayed to the user in place of the value.

commands > command > userCommand > args > arg > userinput > options > value

The value which will be passed as the argument if the user selects this option. Defined as a singleLineString.

commands > command > userCommand > args > arg > userinput > requireArgument

Specifies that the user input argument requires a value to be entered to execute the command.

Note: This is enforced by v4.10.0 Active Consoles and later. Older Active Consoles pass the command to the Gateway, which rejects the command if there is no text provided by the user for the argument.

Default: False

commands > command > userCommand > environmentVariables

Provides another way to share information with a script or library command. For scripts environment variables appear in the standard environment. For library commands environment variables are passed as additional arguments in name=value format. Environment variables are available for Gateway and Netprobe targets.

commands > command > userCommand > environmentVariables > name

A name for the environment variable with the usual restrictions for identifiers.

Mandatory: Yes
commands > command > userCommand > environmentVariables > value

Value for the environment variable. May include Geneos variable references which are resolved when the command is executed. The value of an environemnt variable may be made up of text and variable references. To make it explicit when secure values are used references to secure passwords are replaced with "XXX" at runtime. Secure values should be passed in the secureEnvironmentVariables section.

commands > command > userCommand > secureEnvironmentVariables

Provides a way to send secured information with a script or library command. For scripts secure environment variables appear in the standard environment but remain encrypted. For library commands secure environment variables also remain encrypted and are passed as additional arguments in name=value format. Secure environment variables are available for Gateway and Netprobe targets.

commands > command > userCommand > secureEnvironmentVariables > name

A name for the environment variable with the usual restrictions for identifiers.

Mandatory: Yes
commands > command > userCommand > secureEnvironmentVariables > value

Value for the environment variable.

commands > command > userCommand > enablePassword

This option has a different effect depending on the Run location:

  • Client — No effect. The option is ignored.
  • Gateway — User is asked to enter the Gateway Command Password.
  • Netprobe — User is asked to enter the Netprobe password.
Mandatory: No
Default: false

Task Commands

Task commands allow a sequence of commands to be run against a target data-item as a single command run. For example, this could be used copy an executable onto a system, change its permissions, and then run it.

Task commands are defined in terms of other commands in the Commands section. These can be either user commands or other task commands.

You cannot create a cycle of task commands (e.g. task command A runs task command B which runs task command A again) because this would result in an infinite loop when executing any commands in the cycle. This produces an error in the GSE.

Note: Task commands that contain commands with the Run location Client do not execute.

Supplying arguments for Task Commands

A task can supply some or all of the arguments for its constituent commands. If you supply all of the arguments, the command can be triggered from the Active console, REST interface, or scheduled command without further prompting.

If you do not supply every argument, the Active Console prompts you for the missing arguments before running them. REST and Scheduled invocations fail due to the command not having the correct number of arguments.

Task arguments can either target specific arguments of a commands within the task or concatenate to the previous argument. You can therefore define complex arguments that are shared between commands. For example:

tasks_combined_task

This Task has two commands: step1 and step2. These commands (not shown) have three arguments. The first being the script or executable triggered by these commands. The Task's first argument targets the second argument of step1 and step2. The Task's next argument concatenates the result of a variable. The result of both task arguments form a single command argument that is passed to both commands.

The Task's third to sixth arguments form a single argument for both commands made by combining static text arguments with the result of an XPath and a variable.

The result of the above Task:

<step 1 script> /opt/app/dest/<value of $archive>/home/ <value of xpath>/<value of $input><step 2 script> /opt/app/dest/<value of $archive>/home/ <value of xpath>/<value of $input>

This task can be executed from the AC, REST interface or scheduled with no additional parameters.

Given that arguments can be supplied at the time of execution of user input and evaluated at run-time for variables and XPaths, the task has to receive it's own arguments and assemble them for each command. Another important fact is only user input arguments may be overridden by tasks. A command's arguments are taken as is if unless they're a user input. User inputs may also have a default in which case they do not have to be overridden.

Note: If a Task without a required argument overrides a command with a required argument, then the command fails during runtime if no argument is provided. For more information, see commands > command > userCommand > args > arg > userinput > requireArgument.

Internally the arguments would look something like this:

# argument
1 <step 1 script>
2 /opt/app/dest/
3 $(archive)
4 /home/
5 <xpath>
6 /
7 $(input)
8 <step 2 script>

The task does not repeat it's own arguments where they are shared between commands. Arguments taken from the commands within the task as taken "as is". Therefore we have the scripts from each command but the arguments from the task are not repeated for each one. The task reuses these.

To see why this is important, consider the task above with the text arguments replaced by user input:

Running this on the Active Console would prompt for "Archive name" and "What to archive". If you schedule this task or run from the REST, you need to know which task arguments to target. In this case you would be targeting arguments 3 and 7.

# argument
1 <step 1 script>
2 /opt/app/dest/
3 user input argument 1
4 /home/
5 <xpath>
6 /
7 user input argument 2
8 <step 2 script>

There may be more complicated scenarios where you need to work out how to target the arguments for a task:

  • Take each command in turn in the order specified by the task.
  • Take each argument from the command numbering from 1.
  • If the argument is a user input check for a target argument replacement. Add this command to your list if you haven't added it before.
  • If a targeted argument is followed by concatenate arguments add those and continue numbering if you haven't added them already.

At the end of this you will have a list of arguments that are unique from the task but may have some duplication from arguments taken directly from commands. Any user input arguments left in your list are the arguments you must target and their argument number for the task.

Note: Netprobe commands are generally not published at the time the setup is validated and applied (the applied setup then having to be applied to the connected probes). Probe commands are validated and arguments substituted when the task is executed.

This may result in error messages in the Gateway and execution logs if the arguments are mis-configured.

Configuration

commands > command > task

This section contains the configuration for a task command.

Mandatory: Yes
commands > command > task > commands

List of the commands making up this task command. These can be any other user or task command, provided a cycle of commands if not formed.

Mandatory: Yes
commands > command > task > commands > commandRef

Reference to a command to run in the system. This can be either a user defined command or an internalCommand.

Mandatory: Yes, at least one is required
commands > command > task > commands > commandRef > command

Named reference to another user defined command in the system. This can be either a user command or a task.

Note: Cyclical task dependencies (e.g. task A calls task B which calls task A) are not allowed.

This setting cannot be set if using internalCommand.

commands > command > task > commands > commandRef > internalCommand

Reference to a command defined internally by the system. The full set of commands available is documented in Internal Commands.

This setting cannot be set if using command.

commands > command > task > commands > commandRef > internalCommand > name

Name of a command defined internally by the system. The full set of commands available is documented in Internal Commands.

Mandatory: Yes
commands > command > task > commands > commandRef > stopOnError

Set to stop execution of the task command if this child command fails to execute.

User commands follow the usual UNIX convention, so a script or executable which returns an exit code greater-than zero (>0) is viewed as an execution failure.

Mandatory: Yes
commands > command > task > args

Optional list of command arguments. This list allows you to specify an argument that is passed to several commands. Child commands with user-input arguments not specified in this section will be combined into one list, and displayed as a prompt to the user.

Mandatory: No
commands > command > task > args > arg

An argument definition. This should contain the normal contents of an arg definition described above in Task Commands, and additionally a targetArgs section which describes which child command arguments this definition applies to.

Mandatory: No
commands > command > task > args > arg > concatenate

Boolean setting which controls whether the value of this argument should be concatenated to the previous argument, before being passed to the underlying task. This can be used to build up strings which include variables, similar to using a UNIX shell. E.g. prefix_$(var)_postfix, which would be done using three different arg nodes.

Mandatory: Yes
commands > command > task > args > arg > targetArgs

List of target arguments.

Mandatory: Yes
commands > command > task > args > arg > targetArgs > targetArg

A target argument definition, specifying one of the child command arguments this task command argument should override.

Mandatory: Yes, 1 is required.
commands > command > task > args > arg > targetArgs > targetArg > commandNumber

The index of the child command in the list of commands indexed from 1. Thus 1 is the first command, 2 is the second, and so on.

Mandatory: Yes
commands > command > task > args > arg > targetArgs > targetArg > argNumber

The index of the child command argument to override indexed from 1. 1 is the first argument, 2 is the second, and so on.

Mandatory: Yes
commands > command > task > silent

Set to true to make the task run silently. N no output is written to the ActiveConsole or log file for this task.

Mandatory: No
Default: false
Example task command configuration

An example configuration is shown below. In the example we reference (but do not show) a command "copy" which takes a single static argument and a command "execute" which also takes a single argument. In this example a single user input is used to satisfy both arguments.

The main configuration panel show the two commands being referenced for task apply patch (6). The Argument is configured here (7).

Expanding the "Target Args" dialogue shows that the argument is configured against the first argument of command 1 (copy) and command 2 (execute).

Expanding the UserInput dialogue shows the configuration of the argument. A singleLineString argument with a default of 'Patch Source'.

Changes to Commands arguments parsing behaviour in GA4.7

The behaviour for Commands changed in Geneos v4.7 to ensure consistency when commands are run on the Gateway or Netprobe and to reduce unexpected behaviour. The following principles now apply to Commands:

  • Each argument is passed exactly as written, including spaces, quotes, and backslashes. There are no escape characters. For example, the output from the command below produces unexpected results prior to version 4.7:

    This command prints each argument encased in square brackets and on a new line. In v4.6 and below, this command produces unexpected behaviour. In v4.7, the behaviour is now consistent between the Gateway and the Netprobe and takes each arguments exactly as written:

  • Run Location Version Output
    Gateway 4.6 and below [Line 1 - ]
    [Tes]
    []
    [Line 2 - ]
    [Hello]
    [worl]
    []
    Netprobe 4.6 and below [Line]n[1]n[-]n[Test]n[Line]n[2]n[-]n[Hello world]n
    Gateway 4.7 [Line 1 - "Test"]
    [Line 2 - "Hello world"]
    Netprobe 4.7 [Line 1 - "Test"]
    [Line 2 - "Hello world"]

  • The first argument in a command must either be an executable or a path to an executable (such as a script). Otherwise, the command will fail to execute. This behaviour was inconsistent between Netprobe and Gateway prior to v4.7. For example, the command below would run on the Netprobe but fail on the Gateway:
  • /bin/ls >> tmp.txt
    In v4.7, this command fails to execute on both the Gateway and Netprobe:
    Run LocationVersionOutput
    Gateway 4.6 and belowFailed to run '/bin/ls >> tmp.txt'
    Failed to execute '/bin/ls >> tmp.txt' with arguments ''.
    Exit code: 127 (error executing)
    Netprobe4.6 and belowCommand executes.
    Gateway4.7 and aboveFailed to run '/bin/ls >> tmp.txt'
    Failed to execute '/bin/ls >> tmp.txt' with arguments ''.
    Exit code: 127 (error executing)
    Netprobe4.7 and aboveFailed to run executable '/bin/ls >> tmp.txt' with arguments '' ()
    If you would like your arguments to include redirects or pipes, place the arguments into a script and use the script as the executable.
  • Any empty arguments are passed as blank strings and are not removed from the command.

Note:
1. If you would like to have the new behaviour on the Netprobe, then you must upgrade both Gateway and Netprobe to at least v4.7.
2. If you would like to have the new behaviour on the Gateway, then you need to upgrade the Gateway to at least v4.7.
3. Updating to v4.7 does not alter the behaviour on Windows Netprobes.

Scheduled Commands

Gateway allows the scheduling of any command in the system, including both internally-defined gateway commands and user-defined commands. These commands can be scheduled to run automatically at recurring intervals, or one-off events at a specified time. Scheduled commands run against a list of targets, which are specified using an XPath (see XPaths - User Guide for more information on XPaths). This allows a command to be configured against every Netprobe in the system, for example.

Scheduled commands allow many different schedule types, including at exact specified times, at regular times, or more fuzzy dates such as "the second Friday of each month". Once configured, a scheduled command will execute automatically at the specified time without any further user interaction. The user must therefore provide all required command argument at configuration time, since they cannot be prompted for input when the command is run.

Each run of a scheduled command will produce a log file, containing an execution log as well as any standard output and error streams from the command. The execution information of a particular scheduled command (including the success or failure of this command) is stored in a command history. A configurable number of histories are stored per command, and will persist across restarts of the gateway.

Configuration

All Scheduled Command configuration nodes are placed in the top level node scheduledCommands.

scheduledCommands > logDirectory

The directory to which Scheduled Command log files will be written. If not specified this will default to "." i.e. the working directory of the gateway.

scheduledCommands > historyCount

The number of histories per command that will be persisted. If not supplied this will default to 5.

scheduledCommands > scheduledCommand

Configuration of a single Scheduled Command. This has a mandatory name attribute which must be unique for each Scheduled Command per configuration.

scheduledCommands > scheduledCommand > name

Specifies the name of the scheduled command. This name must be unique within the setup file.

scheduledCommands > scheduledCommand > command

Defines the actual command that will be run as scheduled.

scheduledCommands > scheduledCommand > command > commandRef

A named reference to user-defined command that will be run as scheduled.

scheduledCommands > scheduledCommand > command > internalCommand

Allows the selection of an internal command that will be run as scheduled.

scheduledCommands > scheduledCommand > recurrence

The recurrence node controls the Scheduling part of a Scheduled Command, i.e. what time the command is run and how often it is repeated.

(As this section is complicated it will be described fully in its own section below. Help from the setup editor will still be available on a per sub-item basis)

scheduledCommands > scheduledCommand > args

An optional list of command arguments. This list allows users to specify an argument which will override an argument in the target command. As there is no user interaction at run-time for Scheduled Commands, all user arguments must be overridden for configuration to be valid.

scheduledCommands > scheduledCommand > args > arg

An argument definition. This should contain the normal contents of an arg node described above but excluding userInput option, and additionally a targetArgs tag which describes arguments are being overridden.

scheduledCommands > scheduledCommand > args > arg > stdAES

A secure password type for commands that take password arguments.

scheduledCommands > scheduledCommand > args > arg > targetArgs

Describes the set of arguments that are being overridden.

scheduledCommands > scheduledCommand > args > arg > targetArgs > targetArg

Defines the index of a single argument that is being overridden.

scheduledCommands > scheduledCommand > commandPassword

Defines a password argument to be used with the scheduled command which must match the password set for the probe on which the command is run. This is useful for running scheduled commands against the netprobe. The enablePassword option should be set on the command that is being scheduled.

The password will be AES 256 encrypted by default and variables should be of the same type.

On older gateways it was necessary to set the "enablePassword" option in Command and override the last parameter of the command to be the probe password.

See Secure Passwords.

Mandatory: No
Default: Not set

scheduledCommands > scheduledCommand > targets

A set of XPaths that define a set of data-items that this scheduled command will run against. The command will run against each unique DataItem that matches these XPaths, with the unique XPath as its target. See XPaths - User Guide for more information on XPaths.

Basic Configuration Example

The example below shows an example configuration for a scheduled command.

  1. Select the Scheduled commands top-level section. If this section does not exist, double-click to create it.
  2. Select the New Scheduled Command button to create a new scheduled command.
  3. Set a name for your scheduled command, link it to the command it needs to run and also, specify the target of the command.
  4. Ensure the Advanced tab is visible and select the "Add new" option. This brings up a dialog.
  5. Specify suitable values for the target arguments, clicking the "Add new" button for additional arguments.

Recurrence Configuration Example

As configuration of the recurrence node is complicated, it is given its own section. The recurrence node controls the Scheduling part of a Scheduled Command, i.e. what time the command is run and how often it is repeated.

scheduledCommands > scheduledCommand > recurrence > pattern

Describes the recurrence pattern for the command. Must be one of (minutes, hours, days, weeks, months):

scheduledCommands > scheduledCommand > recurrence > pattern > minutes

Recurs on a minutes basis.

scheduledCommands > scheduledCommand > recurrence > pattern > minutes > everyXMinutes

The number of minutes to recur after.

scheduledCommands > scheduledCommand > recurrence > pattern > minutes > activeTime

A name reference to a valid ActiveTime, which specifies valid times for the Scheduled Command to run.

scheduledCommands > scheduledCommand > recurrence > pattern > hours

Recurs on an hourly basis.

scheduledCommands > scheduledCommand > recurrence > pattern > hours > everyXHours

The number of hours to recur after.

scheduledCommands > scheduledCommand > recurrence > pattern > hours > activeTime

A name reference to a valid ActiveTime, which specifies valid times for the Scheduled Command to run.

scheduledCommands > scheduledCommand > recurrence > pattern > days

Recurs on a daily basis.

scheduledCommands > scheduledCommand > recurrence > pattern > days > everyXDays

The number of days after which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > days > everyWeekDay

Recur every weekday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks

Recurs on a weekly basis.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > days

The days that the command should recur.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > everyXWeeks

The number of days after which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > monday

Recur on a Monday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > tuesday

Recur on a Tuesday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > wednesday

Recur on a Wednesday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > thursday

Recur on a Thursday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > friday

Recur on a Friday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > saturday

Recur on a Saturday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > Sunday

Recur on a Sunday.

scheduledCommands > scheduledCommand > recurrence > pattern > months

Recurs on a monthly basis. There is a choice of one of dayXOfMonth or dayOfMonth:

scheduledCommands > scheduledCommand > recurrence > pattern > months > everyXMonths

The number of months after which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayXofMonth

The numbered day of the month on which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth

Provides more control over monthly scheduling. There is a choice of one of (first, second, third, fourth, last) and (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday) of the month:

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > first

First occurrence in the month.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > second

Second occurrence in the month.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > third

Third occurrence in the month.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > fourth

Fourth occurrence in the month.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > last

Last occurrence in the month.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > Monday

Recur on a Monday.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > tuesday

Recur on a Tuesday.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > wednesday

Recur on a Wednesday.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > thursday

Recur on a Thursday.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > friday

Recur on a Friday.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > saturday

Recur on a Saturday.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > weekday

Recur on a week day.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > weekendday

Recur on a week-end day.

scheduledCommands > scheduledCommand > recurrence > range

Describes when the Scheduling starts and how many times it will recur. There is a choice of noEndDate, endAfterXOccurances and endBy:

scheduledCommands > scheduledCommand > recurrence > range > timezone

Describes what timezone the start and end date (if any) should be interpreted in. This is useful when a Scheduled Command needs to be run in a timezone that is different to the local timezone that the Gateway is running in. The timezone region can be selected from the list.

Mandatory: No
Default: Runs in local timezone
scheduledCommands > scheduledCommand > recurrence > range > start

The Date and Time of the first occurrence. This is in the standard xs:DateTime format.

scheduledCommands > scheduledCommand > recurrence > range > noEndDate

No end date so continue recurring indefinitely.

scheduledCommands > scheduledCommand > recurrence > range > endAfterXOccurances

Absolute number of runs.

scheduledCommands > scheduledCommand > recurrence > range > endBy

The Date and Time after which no more runs will occur. This is in the standard xs:DateTime format.

REST Service

As well as running commands via Geneos clients such as Active Console and Web Dashboard, the Gateway has the ability to enable a REST service that allows any third party application to send requests to the Gateway to run commands, to list available commands and command targets, or to get a validation report for the Gateway setup.

Applications use the REST service by sending POST requests to a Gateway REST service URL.

To enable the REST service on a Gateway:

  1. In the GSE, click Commands.
  2. Select the Advanced tab.
  3. In Rest service, tick the box next to Enabled.

The Gateway REST service supports the following URLs:

  • <protocol>://<host>:<port>/rest/runCommand to run a command. The command to run, the target to run it against and any required arguments are provided in a JSON data package. See Run commands.
  • <protocol>://<host>:<port>/rest/commands/all to list all commands known to the Gateway (except for any commands that are configured to run on the Active Console client.) No additional data is required for this type of request. See List all commands.
  • <protocol>://<host>:<port>/rest/commands/available to list the commands available on a given target. The target and, optionally, a pattern to be matched against the command name are provided in a JSON data package. See List available commands.
  • <protocol>://<host>:<port>/rest/setup/validate to obtain a report listing validation issues for the Gateway setup. No additional data is required for this type of request. See Validate the Gateway setup.
  • <protocol>://<host>:<port>/rest/gatewayinfo/timezone to obtain the Gateway time zone and the offset from UTC. See Obtain the Gateway time zone and offset.
  • <protocol>://<host>:<port>/rest/authorize to obtain an SSO Token. This token can be used to run other REST commands as the authorized user. See Authorise SSO User.

In each case the host is the gateway host and the port is either the gateway's secure listen port, or, if the gateway administrator permits this via the gateway setup, its insecure listen port. If the secure port is used the protocol used is HTTPS, otherwise it is HTTP.

REST Response

The response that is sent back from the gateway depends on the type of response requested by the REST client. The REST client can specify the format it wishes the service to use for its response. The REST service supports 2 formats:

  • application/json
  • text/event-stream

If the REST client requests the service use application/json to return its data then a JSON Response document will be returned. If the REST client requests the service use text/event-stream to return its data then a command output stream will be returned using the Server-sent events protocol.

Currently if there is no match available for any of the requested document types, the REST Service will send a JSON Response document.

JSON Response document

The JSON response document contains some/all of the following fields:

  • mimetype [Optional] - Specifies the mimetype of the data streams that have been sent as part of the response. Currently the Gateway supports 2 mimetypes: ("text/plain", "text/html"). The mimetypes for the streams are dependant on the command that has been run. This is an array as different streams can have different mimetypes.
  • status [Required] - The status of the command. This is either "finished" or "error"
  • streamdata [Optional] - An array of data sent to different ouput streams. The streams currently supported are:
    • stdout - Output stream, where normal output from a command is placed
    • stderr - Error stream, where error output form a command is placed
    • execLog - Information about what external command the gateway/netprobe executed is placed in this stream

The data from the streams can be inter-mingled. Each entry in the "streamdata" array is a JSON item with a field name that matched one of the stream names and a value that contains the data sent to that stream. The items are ordered in the array in chronological order.

The JSON response document is composed once the command has finished. For Streaming commands, or long running commands where the output needs to be examined before the command has finished, this return type should not be used.

Once the message has been sent, the gateway will close the connection to the REST client.

If an error occurs when running the command then the appropriate HTTP status error will be returned. The error codes that the REST service can return are detailed in section HTTP Status codes.

Command output stream

The gateway sends command output streams using Server-sent events (https://www.w3.org/TR/eventsource/).

This information is sent by the gateway as single line events. Each line starts with "data:" and ends with two end-of line markers (\r\n). Between is the command output data, which is always a JSON document. The gateway does not send out event ids or event types.

The structure of the data is similar to the JSON Response document:

  1. When the gateway starts the stream, it sends a mimetype message. This always contains the mime types of all 3 data streams (stdout, stderr, execLog).
  2. This is followed by a set of command output events. Each event is a JSON document with a field name that matches one of the stream names and a value that contains the data sent to that stream.
  3. Finally, the gateway sends a status message with a value of "finished" or "error".

Note: The gateway does not close the connection. It is the responsibility of the REST client to close the connection when it has seen the status message.

Gateway currently does not support reconnecting to command output streams. If the connection is dropped, then the gateway will cancel the command if has not already finished. A client that attempts to reconnect will rerun the command.

Below is an example of a curl command that gets data via the command output stream.

Curl Command

curl -X POST -s -N -H 'Accept: text/event-stream' --data '{
  "command" : "cmd1",
  "target" : "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME1\")]"
}' http://localhost:18066/rest/runCommand

Gateway Response

#Geneos Command Output Stream
data: {"mimetype":[{"execLog":"text/plain"},{"stderr":"text/plain"},{"stdout":"text/plain"}]}

data: {"stdout":"Hello World\n"}
data: {"stdout":"\n"}

data: {"stderr":"\n"}
data: {"execLog":"Finished executing '/bin/echo' with arguments '\"Hello World\"'.\n"}
data: {"execLog":"Exit code: 0 (success)\n"}

data: {"status":"finished"}	

If an error occurs when running the command prior to starting the command output stream then the appropriate HTTP status error will be returned. The error codes that the REST service can return are detailed in section HTTP Status codes. When the command output stream starts, the HTTP status is sent. A status of 200 OK is sent if no error is detected at this point.

Run commands

To run a command, the application sends a POST request to the runCommand URL with a JSON data package which should contain some/all of the following things

  • command [Required] : Name of the command that the REST client requires the gateway to run
  • target [Required] : XPath name that identifies the location in the gateway directory where the command should be run. The xpath need not be the full unique name of an item, but must unambiguously identify a single dataitem. The unique name of an item can be obtained by selecting 'Copy From ... > Path' on the menu attached to each dataitem. (see Target names and relative paths).
  • args [Optional] : Arguments required by the command. Each command is has a number of arguments. The arguments for internal commands are defined in Internal Commands. The arguments for user defined commands are the arguments list defined in Command arguments. Each argument has an index number and the JSON structure of the arguments is a map from the argument number to the value supplied for that argument.

The format of the REST service response can be controlled using HTTP content negotiation. See section REST Response.

This section contains a number of examples of using curl to run commands using the REST API. In all these examples the following assumptions are made:

  • Curl is run on the gateway machine
  • The REST service is configured to service both secure and insecure connections
  • The gateway is listening insecurely on port 7039
  • Gateway name is GW
  • Probe name is P
  • Managed Entity name is ME
  • There is a user command cmd1 that prints "Hello World"

Command with no arguments

This example runs a command with no arguments and gets back the command's response. The command in this example will show the snooze information for Managed Entity ME. In order for this command to return without an error, the Managed Entity ME must be snoozed.

Curl Command

curl -X POST -s --data '{
   "command" : "/SNOOZE:info",
   "target" : "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]"
}' http://localhost:7039/rest/runCommand

Gateway Response

{
	"mimetype": [
		{
			"stdout": "text/plain"
		}
	],
	"streamdata": [
		{
			"stdout": "Data Item           : /geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]\n"
		},
		{
			"stdout": "Snoozed by          : ActiveConsole1\n"
		},
		{
			"stdout": "Snoozed by Fullname : ActiveConsole1\n"
		},
		{
			"stdout": "Snoozed on          : Wed 11 May 2016  10:59:46\n"
		},
		{
			"stdout": "Comment             : Under Maintenance\n"
		},
		{
			"stdout": "Snooze type         : Until specified time\n"
		},
		{
			"stdout": "Unsnoozed     : Wed 11 May 2016  21:59:46\n"
		}
	],
	"status": "finished"
}

Command with no output

An example of a command that returns no data is the Gateway reload command. This is called with a target of the gateway directory and again has no arguments set.

Curl Command

curl -X POST -s --data '{
  "command" : "/GATEWAY:reloadSetup",
  "target" : "/geneos/gateway[(@name=\"GW\")]/directory"
}' http://localhost:7039/rest/runCommand

Gateway Response

{ "status":"finished" }

Command with Arguments

Examples of a commands that needs arguments are the snooze commands. We can use the /SNOOZE:severityTo to snooze a ManagedEntity until its severity changes to a specified value.

This command takes 4 arguments;

  • User Comment : This is a text field that the user sets to remind themselves of why the snooze was applied.
  • Severity : This is an Xpath argument that is normally filled by the Geneos client. In this case it is expected to contain the value of the current severity. The REST client does not need to set this value as the gateway will look up the value from using the xpath and the target. However the REST client can pass a value that will override this value. (It may do this if it wishes to indicate the severity it was working with at the time the command was run).
  • Static value "severityTo". This should never be set by the REST client. The REST Service does not allow static values to be changed.
  • Target Severity : This is the Severity the Gateway will watch for. When the target changes to this severity the gateway will unsnooze the command target. This value is a severity and so should be an integer between 0 and 3.

For our example we will Snooze Managed Entity ME until the severity goes to 'OK' (value 1). We know that currently the severity of the Managed Entity is 'Critical' (value 3) so will inform the gateway of this fact.

Curl Command

curl -X POST -s --data '{
	"command" : "/SNOOZE:severityTo",
       "target" : "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]",
	 "args": {
	 "1": "Remedial work in progress",
	"2": 3,
	"4": 1
	 }
	}' http://localhost:7039/rest/runCommand

Gateway Response

{ "status":"finished" }

User defined Command

A final example is running a User defined command. This command runs the script '/bin/echo "Hello World"', as can be seen from the data returned in the execLog stream.

Curl Command

curl -X POST -s --data '{
	"command" : "cmd1",
	"target" : "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]"
}' http://localhost:7039/rest/runCommand

Gateway Response

{
   "mimetype":[
      {
         "execLog":"text/plain"
      },
      {
         "stderr":"text/plain"
      },
      {
         "stdout":"text/plain"
      }
   ],
   "streamdata":[
      {
         "stdout":"\"Hello World\"\n"
      },
      {
         "stdout":"\n"
      },
      {
         "stderr":"\n"
      },
      {
         "execLog":"Finished executing '/bin/echo' with arguments '\"Hello World\"'.\n"
      },
      {
         "execLog":"Exit code: 0 (success)\n"
      }
   ],
   "status":"finished"
}

List commands

The REST service supports two requests that allow applications to determine what commands are available via the runCommand URL. Both requests return full details of each command, including the targets (XPath locations within the Gateway directory structure) at which it can be run and the arguments it supports.

List all commands

To list all the commands that can be executed via the REST interface, the application sends a GET or POST request to the commands/all URL. No additional parameters are required for this endpoint.

Example usage (assuming a Gateway accepting REST requests on its insecure port and listening on port 7039):

curl -X GET -s http://localhost:7039/rest/commands/all

Note: This endpoint will list all commands, regardless of the permissions required. If authentication is enabled, it is available to any authenticated user.

List available commands

To list the commands available for a specific target the application sends a GET or POST request to the commands/available URL with a JSON package which identifies the target and may specify a regular expression to be used to refine the list of commamds. That is, the POST data is a JSON object with the following keys:

  • target [Required] : XPath name that identifies the location in the gateway directory for which available commands should be listed. This target must match a single data item: the xpath should be the unique name of that dataitem. The unique name of an item can be obtained by selecting 'Copy From ... > Path' on the menu attached to each dataitem. (see Target names and relative paths).
  • namePattern [Optional] : Regular expression (using PCRE syntex) to be matched against command names. Only commands whose names match this pattern will be selected.

Example usage (assuming the probe was snoozed, this would list the /SNOOZE:info and /SNOOZE:manual commands):

curl -X POST -s --data '{
	"target" : "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]",
	"namePattern" : "^/SNOOZE:[mi]"
	}' http://localhost:7039/rest/commands/available

If user authentication is enabled, this endpoint will list only the commands which are available to the user whose credentials are provided in the request.

JSON command list response

The response sent back from the gateway for a successful request to either the commands/all or the commands/available endpoint is a JSON object containing an array of command descriptions:

{
	"commands": [
		{
			"name": "/SNOOZE:manual",
			"menuPath": [
				"Snooze",
				"Manual"
			],
			"groups": [
				"/GATEWAY",
				"/SNOOZE"
			],
			"description": "Snooze until manually unsnoozed",
			"type": "Internal",
			"targets": [
				"/geneos/gateway/directory/probe/managedEntity",
				"/geneos/gateway/directory/probe",
				"/geneos/gateway/directory"
			],
			"arguments": [
				{
					"index": 1,
					"type": "multi-line string",
					"description": "User comment"
				},
				{
					"index": 2,
					"type": "xpath",
					"default": "state/@severity"
				}
			],
			"mimeTypes": [
				{
					"execLog": "text/plain"
				},
				{
					"stdout": "text/plain"
				},
				{
					"stderr": "text/plain"
				}
			]
		},
		{
			"name": "/SNOOZE:info",
			"menuPath": [
				"Snooze",
				"Info"
			],
			"groups": [],
			"description": "Shows snooze information for the selected data item",
			"type": "Internal",
			"targets": [
				"/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell",
				"/geneos/gateway/directory/probe/managedEntity/sampler/dataview[(state(\"snoozed\")=1)]",
				"/geneos/gateway/directory/probe/managedEntity/sampler[(state(\"snoozed\")=1)]",
				"/geneos/gateway/directory/probe/managedEntity[(state(\"snoozed\")=1)]",
				"/geneos/gateway/directory/probe[(state(\"snoozed\")=1)]",
				"/geneos/gateway/directory[(state(\"snoozed\")=1)]"
			],
			"arguments": [],
			"mimeTypes": [
				{
					"execLog": "text/plain"
				},
				{
					"stdout": "text/plain"
				},
				{
					"stderr": "text/plain"
				}
			]
		}
	]
}

The array of commands will be empty if no commands meet the given criteria.

If the request fails, the response is a JSON object containing an error message, for example:

{
"error": "Command target matches more than one item"
}

Find items matching a target

The REST service supports two requests that allow applications to determine what data items are known to the Gateway and which can be specified as targets for a given command. Both these requests return an array of XPath names each of which uniquely identifies a data item.

All items matching a target XPath

To list all items matching a given XPath (regardless of whether any commands are available on the items), the application sends a GET or POST request to the xpaths/match URL with a JSON package which identifies the target and may override the default limit on the number of items returned. That is, the POST data is a JSON object with the following keys:

  • target [Required] : XPath name selecting the data items to list. This path will be evaluated against the whole directory of data items known to the Gateway.
  • limit [Optional] : Integer value to override the default limit of 100 items. By default, if the target path matches more than 100 items, the request will be rejected. Note that attempting to retrieve a very large number of XPaths will force the Gateway to allocate a very large amount of memory to service the request, which may harm its performance.

Example usage, listing all managed entities (assuming that there are fewer than 100):

curl -X GET -o cmdresult.json -s --data '{
	"target":"//managedEntity"
	}' http://localhost:7039/rest/xpaths/match

Note: This endpoint will not take permissions into account. If authentication is enabled, it is available to any authenticated user.

Items which are targets for a given command

To list data items which are valid targets for a given command and which match a given target XName, the application sends a GET or POST request to the xpaths/commandTargets URL with a JSON package which identifies the command and target and may override the default limit on the number of items considered. That is, the POST data is a JSON object with the following keys:

  • target [Required] : XPath name selecting the data items to check as targets of the command. This path will be evaluated against the whole directory of data items known to the Gateway.
  • command [Required] : Name of the command against which to check the data items matching the target XPath.
  • limit [Optional] : Integer value to override the default limit of 100 items. By default, if the path matches more than 100 items (regardless of whether they are valid targets for the command), the request will be rejected. Note that attempting to check a very large number of data items will force the Gateway to allocate a very large amount of memory to service the request, which may harm its performance.

Example usage, listing all managed entities which can be unsnoozed (assuming that there are fewer than 100 managed entities in total):

curl -X GET -o cmdresult.json -s --data '{
	"target":"//managedEntity",
	"command":"/SNOOZE:unsnooze"
	}' http://localhost:7039/rest/xpaths/commandTargets	

If user authentication is enabled, this endpoint will list only the items for which the requesting user can run the command.

JSON XPath list response

The response sent back from the gateway for a successful request to either the xpaths/match or the xpaths/commandTargets endpoint is a JSON object containing an array of XPaths, each of which is the unique name of a data item:

{
	"xpaths": [
		"/geneos/gateway[(@name=\"devGW\")]/directory/probe[(@name=\"theProbe\")]/managedEntity[(@name=\"apps\")]",
		"/geneos/gateway[(@name=\"devGW\")]/directory/probe[(@name=\"theProbe\")]/managedEntity[(@name=\"basics\")]",
		"/geneos/gateway[(@name=\"devGW\")]/directory/probe[(@name=\"vp\")]/managedEntity[(@name=\"GatewayInfo\")]"
	]
}

The array of XPaths will be empty if no data items meet the given criteria.

Run a command against multiple targets

The output of the xpaths/commandTargets endpoint is a list of targets suitable for passing to the runCommand endpoint. To run a command against multiple targets, an application can use the xpaths/commandTargets endpoint to obtain a list of targets and then use the runCommand endpoint to run the command for each target.

The Gateway distribution includes a script, resources\rest\apply-commands.sh, which does just this. For example, to snooze all managed entities whose "Foo" attribute is set to "Bar", the script could be run as follows:

resources/rest/apply-command.sh --target='//managedEntity[attr("Foo")="Bar"]' \\
--command="/SNOOZE:manual" --args='{"1":"Maintenance"}' --gateway=localhost:7039

This script compiles an output file containing details of each runCommand request issued and its results. The default name for this file is apply-command_results_yyyymmdd_hhmm.json, it can be overridden with the --output option.

The script will display full usage information if invoked without arguments or with the --help option.

Validate the Gateway setup

The REST service allows applications to validate the setup of a running gateway. The setup/validate endpoint does not require any additional parameters.

Example usage (assuming a gateway accepting REST requests on its insecure port and listening on port 7039):

curl -X GET -s http://localhost:7039/rest/setup/validate

If authentication is enabled, this endpoint is available only to users with setup view (or apply) permission for the main gateway setup file.

The response shows the overall status of the gateway setup (the maximum severity of any issue detected) and a list of issues. For example, if there are no issues, the response will be

{
	"validationResult": {
		"maxSeverity": "None",
		"issues": []
	}
}

When there are problems with the setup, the response includes details of each issue, including the XPath within the setup and the name of any relevant include file:

{
	"validationResult": {
		"maxSeverity": "Error",
		"issues": [
			{
				"severity": "Error",
				"module": "CommandManager",
				"description": "Command name is missing or empty - skipping this command definition.",
				"xpathLocation": "/gateway[@disabled!=\"true\"][1]/commands[@disabled!=\"true\"][1]/commandGroup[@disabled!=\"true\"][1]/command[@disabled!=\"true\"][1]",
				"includeFile": "smartTk.setup.xml"
			},
			{
				"severity": "Warn",
				"module": "RestService",
				"description": "Invalid value 'true' for maxBufferSize setting, expecting Integer value. Using default of '1024",
				"xpathLocation": "/gateway[@disabled!=\"true\"][1]/commands[@disabled!=\"true\"][1]/restService[@disabled!=\"true\"][1]/maxBufferSize[@disabled!=\"true\"][1]"
			}
		]
	}
}

Obtain the Gateway time zone and offset

The remote Gateway time zone and the offset from Coordinated Universal Time (UTC) is retrieved using this REST endpoint. This enables you to issue remote REST commands with date and time parameters without having to first calculate the time difference.

The timezone name in the response is the first existing value from the following:

  1. The time zone specified in the operatingEnvironment > timezone configuration setting.
  2. The value of the TZ environment variable.
  3. (Linux only) The part after the string "/zoneinfo/" from the value of the /etc/localtime symbolic link.

The timezone name only appears in the response if a value was obtained from one of the above.

The offset from UTC is calculated from the difference between the results of calling gmtime and localtime.

Note: The endpoint does not assess permissions. If authentication is enabled, it is available to any authenticated user.

Response

{
"gatewayinfo": {
	"timezone":"Europe/London",
	"localTime": "2018-05-22T03:25:07",
	"offsetFromUtc": "+01:00"
	}
}

Authorise SSO User

To run REST commands as an SSO user, you need to supply an SSO token in your REST request. The authorize REST endpoint provides you with a token, by redirecting your HTTP client (for example, Curl), to the SSO Agent.

Below is an example of a curl command to obtain an SSO token. This assumes that the SSO Agent has been setup to use Kerberos. For an example showing how to use this token in a subsequent REST request, see User Authentication.

This endpoint relies upon the SSO Authentication setting authentication > sso > ssoAgent. If this setting is not present then the REST service will refuse all connections that use an SSO Agent token to provide user authentication.

Curl Command

curl -L --location-trusted --negotiate --user : -X GET -s -N http://localhost:18066/rest/authorize

SSO Agent Response

{
"access_token": "eyJhbGciOiJSUzI1N........",
"expires": 1500029878,
"token_type": "Bearer"
}

Note: the token is valid only for the Gateway from which it was requested and has an expiry time. Once the time expires the token can no longer be used to run REST commands and a new token must be obtained.

You will usually need to parse the token out of the response from the SSO Agent and capture it in a shell variable. If you have installed the jq utility you could use a command line like this:

SSO_TOKEN=$(curl -L --location-trusted --negotiate --user : -X GET -s -N http://localhost:18066/rest/authorize | jq -r '.access_token')

HTTP Status codes

The following HTTP error codes will be returned if the REST service encounters an error:

  • OK (200): This will be returned if the REST service runs the command successfully.
  • Bad Request (400): This will be returned if the POST data is not well-formed JSON or if a mandatory item is missing.
  • Forbidden (403): This will be returned if the user provides invalid credentials (and credentials are required). It will also be returned if the user's credentials are correct but the user does not have permission to run the command requested on the target requested.
  • Not Found (404): This will be returned if the service is not available. It can occur if the gateway is not running a REST service. It can also occur if the REST service is secure but the request is made on the gateway's insecure port.
  • Internal Server Error (500): This will be returned if the command run returns an error.

HTTPS Connections

If the gateway is setup to allow secure connections, it is possible to use the HTTPS protocol rather than the HTTP one. The REST client will need to implicitly trust the gateway's certificate if its certificate authorities have not signed it.

It is possible to configure the REST service to only run on secure connections. (See restService > allowOnInsecureComms)

User Authentication

If the gateway is configured with authentication enabled, then all REST command requests must come with user credentials that the gateway can verify.

The REST service supports two types of user credentials. SSO tokens can be used to authenticate SSO users. User name and password can be used to authenticate users who have passwords configured in the gateway setup.

System logins are not supported, since system credentials are checked by the user interface client (e.g. Active Console), which is not involved in the REST API. However, it is possible to use System login for Active Console users while using password-based authentication for the REST API.

For password-based authentication, each REST command must be accompanied by a username and password, using HTTP basic access authentication. For example, using Curl:

curl -u rest_user:foo39BAR -X POST -s --data 
	'{
	"command" : "/SNOOZE:info",
	"target" : "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]"
	}' http://localhost:7039/rest/runCommand

Note: this involves sending the users name and password in an HTTP Authorization Header as part of the REST request. This will be base64-encoded by the REST client (Curl in the example above), but not encrypted or hashed. For this reason it is recommended that when authentication is enabled, the REST service is restricted to run on secure connections only.

For SSO based authentication, each REST command must be accompanied by an SSO token. This token can be obtained using the Rest service /rest/authorize. Once the token has been obtained, REST commands can be run by providing the token in the Authorization header. For example, using Curl and assuming that the shell variable SSO_TOKEN contains the SSO access token:

curl -H "Authorization: Bearer $SSO_TOKEN" -X POST -s --data 
					'{
"command" : "/SNOOZE:info",
"target" : "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]"
}' http://localhost:7039/rest/runCommand

While this does not send the user’s password in the token, it is still recomended that the REST service is restricted to run on secure connections only, so that the token cannot be hijacked.

When a user has been authenticated, the user's permissions will be checked against the command and the target data item on which the will be run. The command will only be run if the user has the right to run the command on the specified target. (See Permissions)

Configuration

commands > restService

This section contains the configuration for the gateway REST service. If the section does not exist then the REST service is not enabled.

Mandatory: No
Default: REST service disabled

commands > restService > enabled

Boolean value controlling whether REST service is enabled or not.

Mandatory: No
Default: false

commands > restService > allowOnInsecureComms

This flag enables the REST service to work on both secure and insecure connections. Thus allowing HTTP and HTTPS connections. The HTTP requests need to be made to the gateway's insecure listen port while the HTTPS requests need to be made to the gateway's secure listen port.

Mandatory: No
Default: false

commands > restService > maxBufferSize

This is the maximum size of a single command buffer (in Kb). When requesting JSON response, the gateway buffers all the data until the command has complete. If the command is a streaming command, this may never happen and the buffer will grow as more and more data is received.

Should the data buffer exceed this size, then the gateway will cancel the command and return the currently generated output with an error message indicating that the command buffer has been exceeded.

Mandatory: No
Default: 1024 Kb

Appendix: Internal Commands

Introduction

This appendix provides information on commands available on the Gateway and from Netprobes. The specifics of commands and command targets vary depending on your Gateway setup. To get a list of commands that is accurate to your Gateway, see REST Service.

System commands

System commands are commands which allow control of the system.

Snooze commands

Snooze commands allow control over the gateway snooze functionality.

Note: Most snooze commands have two forms of the command, named as follows:

    /SNOOZE:<name>, for example /SNOOZE:untilChanges

    /SNOOZE:<name>AllMe, for example /SNOOZE:untilChangesAllMe

In these cases the short named version of the command is available for directory, probe and managedEntity data-items. The longer AllMe version of the command is available for sampler, dataview and cell data-items. The AllMe versions have an additional parameter (labelled 'Snooze on' in the GUI) which allows the command to be run on a single managedEntity or multiple managedEntities matching by sampler or plug-in.

An exception to this convention is /SNOOZE:untilValueChanges which is valid on cell data-items only.

Note: Snoozing until severity changes may not work as expected if severity changes to 'undefined'.

If the rule(s) which apply to an item ever set its severity to undefined, then the following scenario is possible:

  • The item is snoozed 'until severity changes' when the severity is OK, Warning or Critical.
  • The host gateway or the source of data (netprobe or gateway) is restarted.
  • The severity of the item is recalculated as 'undefined' after the restart.

Because data items are created with undefined severity and the unsnoozing mechanism depends on detecting a change in severity, the item remains snoozed.

If the item were to be automatically unsnoozed in this scenario, it would also be (wrongly) unsnoozed even if its severity was about to be reset to the previous value (such as Critical) by a rule.

In general, ITRS recommends that the severity of a data item should not be explicitly set to undefined by a rule.

/SNOOZE:manual

Path Snooze/Manual
Long Description Snooze until manually unsnoozed
Effect Snoozes a data-item until manually unsnoozed by a user using the /SNOOZE:unsnooze command.

Targets

/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static manual
4 Static 0

/SNOOZE:manualAllMe

Path Snooze/Manual
Long Description Snooze until manually unsnoozed with options to snooze on all managedEntities.
Effect Snoozes a data-item until manually unsnoozed by a user using the /SNOOZE:unsnooze command.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static manual
4 Static 0
All ManagedEntities 5 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:severityTo

Path Snooze/Severity to
Long Description Snooze until severity changes to…
Effect Snoozes a data-item until the severity of the data-item changes to the specified value.

Targets

/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static severityToOrTime
Target severity 4 User input: Integer 1

/SNOOZE:severityToAllMe

Path Snooze/Severity to
Long Description Snooze until severity changes to… with options to snooze on all managedEntities.
Effect Snoozes a data-item until the severity of the data-item changes to the specified value.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static severityToOrTime
Target severity 4 User input: Integer 1
All ManagedEntities 5 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:untilChanges

Path Snooze/Until changes
Long Description Snooze until severity changes
Effect Snoozes a data-item until the severity of the data-item changes from the severity when it was snoozed.

Targets

/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static severityFrom
4 Static 0

/SNOOZE:untilChangesAllMe

Path Snooze/Until changes
Long Description Snooze until severity changes, with options to snooze on all managedEntities.
Effect Snoozes a data-item until the severity of the data-item changes from the severity when it was snoozed.

Target

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static severityFrom
4 Static 0
All ManagedEntities 5 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:time

Path Snooze/Time period
Long Description Snooze for a specified time period
Effect Snoozes a data-item for the specified time period from the time at which the snooze command is executed.

Targets

/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static time
Duration 4 User input: Float 24
5 User input: Options Hours (3600), Minutes (60), Days (86400)

/SNOOZE:timeAllMe

Path Snooze/Time period
Long Description Snooze for a specified time period, with options to snooze on all managedEntities.
Effect Snoozes a data-item for the specified time period from the time at which the snooze command is executed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static time
Duration 4 User input: Float 24
5 User input: Options Hours (3600), Minutes (60), Days (86400)
All ManagedEntities 6 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:dateTime

Path Snooze/Until Date / Time
Long Description Snooze until a specified date and time
Effect Snoozes a data-item until the specified date and time.

Targets

/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static dateTime
Date 4 User input: String YYYY-MM-DD format. YYYY-MM-DD defaults to today's date.
Time 5 User input: String HH:MM timezoneRegion
24hr clock format time, optional timezoneRegion.
HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used. See Snooze Until Command for more info.

/SNOOZE:dateTimeAllMe

Path Snooze/Until Date / Time
Long Description Snooze until a specified date and time, with options to snooze on all managedEntities.
Effect Snoozes a data-item until the specified date and time.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static dateTime
Date 4 User input: String YYYY-MM-DD format. YYYY-MM-DD defaults to today's date.
Time 5 User input: String HH:MM timezoneRegion
24hr clock format time, optional timezoneRegion.
HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used. See Snooze Until Command for more info.
All ManagedEntities 6 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:severityToOrTime

Path Snooze/Severity to
Long Description Snooze until severity changes to Critical/Warning/Undefined/Ok Or Snooze for specified time period.
Effect Snoozes a data-item until the severity of the data-item changes to the specified value or the time period expires.

Targets

/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static severityTo
Target severity 4 User input: Integer 1
5 Static time
Duration 6 User input: Float 24
7 User input: Options Hours (3600), Minutes (60), Days (86400)

/SNOOZE:severityToOrTimeAllMe

Path Snooze/Severity to
Long Description Snooze until severity changes to Critical/Warning/Undefined/Ok Or Snooze for specified time period with options to snooze on all managedEntities.
Effect Snoozes a data-item until the severity of the data-item changes to the specified value or the time period expires.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static severityTo
Target severity 4 User input: Integer 1
5 Static time
Duration 6 User input: Float 24
7 User input: Options Hours (3600), Minutes (60), Days (86400)
All ManagedEntities 8 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:untilValueChanges

Path Snooze/Until Value Changes
Long Description Snooze a cell until its value changes.
Effect Snooze a cell for as long as its value remains the same as the point at which it was snoozed. This is valid for cell data-items only.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static untilValueChanges
Duration 4 XPath @value
All ManagedEntities 5 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:unsnooze

Path Snooze/Unsnooze
Long Description Unsnooze a snoozed item.
Effect Unsnoozes a snoozed item immediately, and cancels any snooze conditions upon that item (e.g. until severity changes).

Targets

/geneos/gateway/directory/probe/managedEntity[(state(\"snoozed\")=1)]
/geneos/gateway/directory/probe[(state(\"snoozed\")=1)]
/geneos/gateway/directory[(state(\"snoozed\")=1)]

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString

Note: The user comment argument is part of the command only if Require Snooze Comments is enabled. See commands > requireSnoozeComments.

/SNOOZE:unsnoozeAllMe

Path Snooze/Unsnooze
Long Description Unsnooze a snoozed item, with options to unsnooze on all managedEntities.
Effect Unsnoozes a snoozed item immediately, and cancels any snooze conditions upon that item (e.g. until severity changes).

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview[(state(\"snoozed\")=1)]
/geneos/gateway/directory/probe/managedEntity/sampler[(state(\"snoozed\")=1)]

Arguments

Description Arg Type (Default) Value
All ManagedEntities 1 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)
User comment 2 User input: MultiLineString

Note: The user comment argument is part of the command only if Require Snooze Comments is enabled. See commands > requireSnoozeComments.

/SNOOZE:info

Path Snooze/Info
Long Description Shows snooze information for the selected data-item.
Effect Displays details on a snoozed data-item, including the time, username, comments and options selected when snoozing the item.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview[(state(\"snoozed\")=1)]
/geneos/gateway/directory/probe/managedEntity/sampler[(state(\"snoozed\")=1)] /geneos/gateway/directory/probe/managedEntity[(state(\"snoozed\")=1)] /geneos/gateway/directory/probe[(state(\"snoozed\")=1)] /geneos/gateway/directory[(state(\"snoozed\")=1)]

Arguments

None

/SNOOZE:unsnoozeAbsentItems

Path Snooze/unsnooze Absent Items
Long Description Unsnoozes items that are marked as snoozed but not present in the gateway.
Effect All items that are snoozed but not present within the gateway's directory will be unsnoozed (removed). This is useful as a maintenance measure to ensure that gateway performance isn't impacted by these on start-up.

Targets

/geneos/gateway/directory
/geneos/gateway/directory/probe
/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-snoozeData\")]/dataview/headlines/cell[(@name=\"snoozedButAbsentItems\")]

Arguments

Description Arg Type (Default) Value
Confirmation 1 User input: Boolean false

Snooze until command

The /SNOOZE:untilcommand is a generic command which snoozes a DataItem until one of the following four conditions are met:

  • Value Change (only applicable for /SNOOZE:untilAllMeCell)
  • Severity Change (either SeverityFrom or SeverityTo one of Critical/Warning/Undefined/Ok)
  • Time Period (n * Hours/Minutes/Days)
  • Date/Time (Optional Date and Time)

A checkbox is provided to tick a particular condition to be included for Snooze until command. If none of the above conditions are ticked, then the data-item is not snoozed and error is reported. If both Time Period and Date / Time is ticked with valid values, then the DataItem is snoozed until the earliest time (Time vs Date /Time) is reached.

The Time argument can also optionally include the time zone region in the form HH:MM timezoneRegion (for example, 14:20 Europe/London). If a time zone region is not provided, the Gateway's time zone will be used.

The list of supported time zone regions is found in the date_time_zonespec.csv file in the Gateway /resources directory, provided as part of the Gateway bundle (see Time Zones and Time Formats for more information).

There are 3 versions of /SNOOZE:until command:

  • /SNOOZE:until which applies to directory, probe and managedEntity data-items.
  • /SNOOZE:untilAllMe which applies to sampler and dataview.
  • /SNOOZE:untilAllMeCell which applies to cell data-items.

/SNOOZE:untilAllMe and /SNOOZE:untilAllMeCell commands have additional parameter which allows the command to be run on a single managedEntity or multiple managedEntities matching by sampler or plug-in.

/SNOOZE:until

Path Snooze/Until Severity/Time/ Date / Time
Long Description Snooze until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached
Effect Snoozes a data-item until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached

Targets

/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static until
Value 4 Static Value (Unused)
5 Static 0 (Unused)
Severity 6 User input: Boolean false
7 User input: Options severityFrom (0), severityTo(1)
Target severity 8 User input: Integer 1
Time 9 'User input: Boolean" false
Duration 10 User input: Float 24
11 User input: Options Hours (3600), Minutes (60), Days (86400)
Date/Time 12 User input: Boolean false
Date 13 User input: String YYYY-MM-DD format. YYYY-MM-DD defaults to today's date.
Time 14 User input: String HH:MM timezoneRegion
24hr clock format time, optional timezoneRegion.
HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used.

/SNOOZE:untilAllMe

Path Snooze/Until Severity/Time/ Date / Time
Long Description Snooze until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached with options to snooze on all managedEntities
Effect Snoozes a data-item until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static until
Value 4 Static Value (Unused)
5 Static 0 (Unused)
Severity 6 User input: Boolean false
7 User input: Options severityFrom (0), severityTo(1)
Target severity 8 User input: Integer 1
Time 9 User input: Boolean false
Duration 10 User input: Float 24
11 User input: Options Hours (3600), Minutes (60), Days (86400)
Date/Time 12 User input: Boolean false
Date 13 User input: String YYYY-MM-DD format. YYYY-MM-DD defaults to today's date.
Time 14 User input: String HH:MM timezoneRegion
24hr clock format time, optional timezoneRegion.
HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used.
All ManagedEntities 15 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

/SNOOZE:untilAllMeCell

Path Snooze/Until Value/Severity/Time/ Date / Time
Long Description Snooze a cell until value or severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached with options to snooze on all managedEntities
Effect Snoozes a cell until value or severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static until
Value 4 User input: Boolean false
5 XPath @value
Severity 6 User input: Boolean false
7 User input: Options severityFrom (0), severityTo(1)
Target severity 8 User input: Integer 1
Time 9 User input: Boolean false
Duration 10 User input: Float 24
11 User input: Options Hours (3600), Minutes (60), Days (86400)
Date/Time 12 User input: Boolean false
Date 13 User input: String YYYY-MM-DD format. YYYY-MM-DD defaults to today's date.
Time 14 User input: String HH:MM timezoneRegion
24hr clock format time, optional timezoneRegion.
HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used.
All ManagedEntities 15 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)

User Assignment commands

Runs command that allow control over the user assignment functionality.

/USERASSIGNMENT:unassign

Path User Assignment/Unassign
Long Description Cancel a user assignment
Effect Unassigns an assigned item immediately, and cancels any conditions upon that item (e.g. comment).

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview[(state(\"userAssigned\")=1)]
/geneos/gateway/directory/probe/managedEntity/sampler[(state(\"userAssigned\")=1)]
/geneos/gateway/directory/probe/managedEntity[(state(\"userAssigned\")=1)]
/geneos/gateway/directory/probe[(state(\"userAssigned\")=1)]
/geneos/gateway/directory[(state(\"userAssigned\")=1)]

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString

Note: The user comment argument is part of the command only if Require User Assignment Comments is enabled. See commands > requireUserAssignmentComments.

/USERASSIGNMENT:info

Path User Assignment/Info
Long Description Shows user assignment information for the selected data-item.
Effect Displays information on the assigned data-item including assignment time, data-item name, assigned user, assigned by and comment.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview[(state(\"userAssigned\")=1)]
/geneos/gateway/directory/probe/managedEntity/sampler[(state(\"userAssigned\")=1)] /geneos/gateway/directory/probe/managedEntity[(state(\"userAssigned\")=1)] /geneos/gateway/directory/probe[(state(\"userAssigned\")=1)] /geneos/gateway/directory[(state(\"userAssigned\")=1)]

Arguments

None

/USERASSIGNMENT:assignToMe

Path User Assignment/Assign To Me
Long Description Assign DataItem to a user
Effect Assigns the selected data-item to the user logged onto that Gateway.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User comment 1 User input: MultiLineString

/USERASSIGNMENT:assign

Path User Assignment/Assign
Long Description Assign DataItem to a user
Effect Assigns the selected data-item to the user entered by the caller.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User input: MultiLineString

/USERASSIGNMENT::assignUntilSeverityChangesTo

Path User Assignment/Assign Until Severity Changes To
Long Description Assigned until severity changes to a specific one.
Effect Assigns the selected data-item to the user entered by the caller until the severity matches the specified one.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Target severity 3 User Input: Float

/USERASSIGNMENT::assignUntilSeverityChangesFrom

Path User Assignment/Assign Until Severity Changes
Long Description Assigned until severity changes from the current one
Effect Assigns the selected data-item to the user entered by the caller until the severity no-longer matches the current one.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Severity 3 XPath state/@severity

/USERASSIGNMENT::assignForTimePeriod

Path User Assignment/Assign For Time Period
Long Description Assign For Time Period
Effect Assigns the selected data-item to the user entered by the caller until a time period has elapsed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Severity 3 XPath state/@severity
Duration 4 User Input: Float 24
Duration units 5 User input: Options Hours (3600), Minutes (60), Days (86400)

/USERASSIGNMENT::assignUntilDateTime

The Time argument can also optionally include the time zone region in the form HH:MM timezoneRegion (for example, 14:20 Europe/London). If a time zone region is not provided, the Gateway's time zone will be used.

The list of supported time zone regions is found in the date_time_zonespec.csv file in the Gateway /resources directory, provided as part of the Gateway bundle (see Time Zones and Time Formats for more information).

Path User Assignment/Assign Until Date / Time
Long Description Assign Until Date / Time
Effect Assigns the selected data-item to the user entered by the caller until a specific date time

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Severity 3 XPath state/@severity
Date 4 User input: String YYYY-MM-DD format. YYYY-MM-DD defaults to today's date.
Time 5 User input: String HH:MM timezoneRegion
24hr clock format time, optional timezoneRegion.
HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used.

/USERASSIGNMENT::assignUntilSeverityChangeOrTimePeriod

Path User Assignment/Assign Until Severity Change or Time
Long Description Assign Until Severity Change or Time
Effect Assigns the selected data-item to the user entered by the caller until a time period has elapsed or the severity changes from the current.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Target Severity 3 User Input: Integer
Severity 4 XPath state/@severity
Duration 5 User Input: Float 24
Duration units 6 User input: Options Hours (3600), Minutes (60), Days (86400)

/USERASSIGNMENT::assignUntilValueChanges

Path User Assignment/Assign Until Value Changes
Long Description Assign Until value changes
Effect Assigns the selected data-item to the user entered by the caller until the value of the current item changes.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Current value 3 XPath @value

/USERASSIGNMENT:unassignAbsentItems

Path User Assignment/Assign Absent Items
Long Description Unassigns items that are assigned to users but are not present in the gateway.
Effect All items that are assigned to users but not present within the gateway's directory will be unassigned (removed). This is useful as a maintenance measure to ensure that gateway performance isn't impacted by these on start-up.

Targets

/geneos/gateway/directory
/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-userAssignmentData\")]/dataview/headlines/cell[(@name=\"assignedButAbsentItemsCount\")]

Arguments

Description Arg Type (Default) Value
Confirmation 1 User input: Boolean false

/USERASSIGNMENT:assignUntilOk

Path User Assignment/Assign Until OK
Long Description Assigns the cell until severity is OK
Effect Assign the selected data-item to the user until the severity changes to OK.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

If the data-item is already OK then it will remain assigned until it has been another severity and then has become OK again.

Arguments

Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Severity 3 XPath state/@severity

Alert commands

Alert command allows access to additional features of alert manager.

/ALERTS:showAlerts

Path Show Alerts
Long Description Get information about the alert
Effect Displays configuration information about all the alerts that are applicable for the selected data-item. Alerts are displayed formatted, with a similar display to that used in the Gateway Setup Editor.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell

Arguments

None

Rule commands

Rule commands allow access to additional features of rule manager.

/RULES:showRules

Path Show Rules
Long Description Get information about the rules.
Effect

Displays information about any rules which apply to the selected data-item.

Rules are displayed formatted, with a similar display to that used in the Gateway Setup Editor.

Path aliases used within the rule are shown in a table. The table has three columns:

  • name — Name of the path alias.
  • first matching value — First matching value of the path alias.
  • number of matches —Total number of matches of the path alias.

To view the path, hover over the name of the path alias.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
Output format version 1 XPath /geneos/client/features/@RuleShowEx
       

/RULES:showVariables

Path Show Variables
Long Description Get information about the variables available on command target
Effect Displays information about the configured variables available on a target. The command shows the name, type, value, source (either main setup or include file name) and path to where it's configured. Variable values are displayed in a JSON like format to make reading of complex variables easier. For example : All of the macros available at that level of the directory hierachy are shown. These are values that the gateway will fill in for you when used as the value of a variable. Variables defined as a macro are a special given that the Gateway replaces the macro name with a constant. As such there's no meta-data associated with the variable and it isn't possible to show the source or setup path. This isn't such a great issue as the value will be the same no-matter where you define it.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

None

/RULES:ShowRuleContention

Path Show Rule Contention
Long Description Shows rule targets with more than one rule which may be the cause of rule contention.
Effect Displays a list of rule targets for which there is more than one rule, which can cause rule contention. For each target the rule definition path and file in which it is defined is shown. The target is broken down into a simplified user readable xpath as per the path editor of active console. e.g. gateway/probe/sampler(type=")/dataview/row/column

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe /geneos/gateway/directory

Arguments

None

Sampler commands

Sampler commands allow control over samplers and sampling.

/PLUGIN:sampleNow

Path SampleNow
Long Description Execute a sample immediately
Effect Forces a sampler to sample immediately. If executed on a managed entity, this command forces all samplers within that managed entity to sample immediately.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe
/managedEntity

Arguments

None

Reload commands

Reload commands allow reloading the gateway setup file(s).

ReloadSetup command is set on the Gateway. Hence, the target XPath for this should be set to /geneos/gateway/directory. It takes on parameter which is optional. If not specified, then all files will be reloaded. If specified, then it will reload the relevant file or group. If you run the command manually you'll see in the dropdown what needs to be specified. In particular, if you want to specify a group of includes you need to put the / after it, as it is in the dropdown.

ReloadSetupFile is for the Gateway-includesData plugin, for the file column and looks up the setup file name from the cell value. So, you need to set the target XPath to be the correct cell and specify no parameters.

/GATEWAY:reloadSetup

Path Reloads selected setup file(s)
Long Description Reloads all or selected gateway setup file(s).
Effect Reloads all or selected gateway setup file(s).

Targets

/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
File to reload 1 User input: Options All, Main file, All includes, Names of all includes files to select from.

/GATEWAY:reloadSetupFile

Path Reloads the include file.
Long Description Reloads the include file whose target path is provided from the Gateway-includesData plugin.
Effect Reloads the include file whose target path is provided from the Gateway-includesData plugin.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-includesData\")]/dataview/rows/row/cell[(@column=\"file\")]

Arguments

None

Message commands

Message commands allow user messaging via the gateway.

/GATEWAY:broadcastMessage

Path Message Broadcaster
Long Description Sends a ticker event message to all users on this Gateway
Effect Produces a ticker event with the specified severity and message, which is logged and distributed to all connected users via the EventTicker.

Targets

/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
Message 1 User input: MultiLineString
Message Severity 2 User input: Options OK (1), Warning (2), Critical (3), Undefined (0)

Database Logging commands

Database commands allow temporary changes to be made to the scope of item value logging as well as pausing or resuming the database connection.

/DATABASELOGGING:itemValues:discard

Description Discards item value updates from logging.
Long Description The item value updates are discarded and not logged to database. When discarded, the item value updates are lost and cannot be retrieved. This command does not affect the logging of other things such as events, attributes, audit records, etc. to the database.
Effect Item value updates are lost and not logged to database.

Targets

/geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"false\")]
/geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"false\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell

Arguments

None

/DATABASELOGGING:itemValues:log

Description Resumes logging of item value updates
Long Description Resumes logging of item value updates to the database. In this case, everything is logged to the database (item value updates, events, attributes, audit records, null, etc.).
Effect Item value updates are again logged to database.

Targets

/geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"true\")]
/geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"true\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell

Arguments

None

/DATABASELOGGING:connection:pause

Description Completely pause database logging
Long Description Completely pauses logging of anything (item values, events, attributes, audit records etc) to database. Should be issued when the database is down for maintenance.
Effect Database connection is dropped and nothing is logged to database. However, everything is cached and/or written to dump files, so there is no loss of data. This cached/dumped data can be manually/automatically re-inserted back into the database later using -process-dump-files option or by issuing /DATABASELOGGING:connection:resume command.

Targets

/geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"false\")]
/geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"false\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell

Arguments

None

/DATABASELOGGING:connection:resume

Description Resumes database logging
Long Description Re-activates logging (of item values, events, attributes etc) to database. Could be issued when the database is up again for re-use after downtime or maintenance.
Effect Database connection (which was earlier paused by issuing /DATABASELOGGING:connection:pause command) is re-established and logging continues as normal. Dump files can be either automatically or manually read to insert data to database.

Targets

/geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"true\")]
/geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"true\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell

Arguments

None

Reporting commands

Reporting commands allow for user interaction with the express reporting component of the gateway.

/REPORT:generateRun

Path Generate Report Run
Long Description Tells the gateway to generate a report run
Effect Produces a set of reports based on the reports configured for that run.

Targets

/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
Name of the report run 1 Static
       

/REPORT:deleteRuns

Path Delete Report Runs
Long Description Tells the gateway to delete all reports older than x amount of days
Effect Deletes from disk the reports generated by the gateway.

Targets

/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
Minimum age of reports to be deleted (days) 1 Static
Delete scheduled commands (true/false) 2 Static
Delete non-scheduled commands (true/false) 3 Static

Netprobe commands

/PROBE:disableSelfAnnouncing

Description Disables Self Announcing
Long Description Disables Self Announcing mode and updates netprobe setup file
Effect Disables netprobe Self Announcing mode (if configured). Probes remain up and monitoring but will modify their setup files to disable self-announcing mode.

Targets

/geneos/gateway/directory/probe[(rparam(\"SelfAnnouncingEnabled\")=\"true\")][(param(\"reverseConnectionRequired\")!=\"true\")]

Arguments

None

/PROBE::disassociate

Only use this command when a self-announcing Netprobe (SAN) has failed, or when the SAN has moved to another Gateway but the original Gateway was not notified.

This command is available on SANs with a connection status that is not Up or WaitingForProbe. It is not available on imported SANs.

Description Disassociate a self-announcing Netprobe (SAN) from a Gateway.
Long Description Forcibly disassociates a SAN from a Gateway.
Effect

Forces the probe to be removed from the Gateway.

Caution:  If the SAN is up when this command is used, it may connect to a different Gateway. If the SAN does connect to a different Gateway, any snooze or user assignment information is lost.

Targets

/geneos/gateway/directory/probe[(rparam(\"SelfAnnouncingEnabled\")=\"true\")][(rparam(\"ConState\")!=\"Up\")][(rparam(\"ConState\")!=\"WaitingForProbe\")]

Arguments

None

/PROBE:suspend

Description Suspend probe
Long Description Suspends connection to a Netprobe
Effect Gateway temporarily disables connection to the selected Netprobe for a period of time, as if the probe had been disconnected by the Data Quality control feature.

Targets

/geneos/gateway/directory/probe[(rparam(\"ConState\")!=\"Suspended\")]
/geneos/gateway/directory/probe[(rparam(\"ConState\")!=\"Suspended\")]/managedEntity

Arguments

None

/PROBE:unsuspend

Description Unsuspend probe
Long Description Unsuspends connection to a Netprobe.
Effect Gateway resumes connection to the selected Netprobe, if it had been suspended. Suspension may occur due to execution of the "suspend probe" command (see above), or automatically by the Data Quality feature of gateway.

Targets

/geneos/gateway/directory/probe[(rparam(\"ConState\")=\"Suspended\")]
/geneos/gateway/directory/probe[(rparam(\"ConState\")=\"Suspended\")]/managedEntity

Arguments

None

Gateway Sharing commands

/PROBE:suspendImported

Description Suspend Imported probes
Long Description Suspends importing connection for imported probes
Effect Gateway temporarily disables connection to the exporting gateway that the selected probe was imported from. It is as if the importing connection had been disconnected by the Data Quality control feature.

Targets

/geneos/gateway/directory/probe[(rparam(\"ImportedConState\")!=\"Suspended\")][(param(\"Imported\")=\"true\")]
/geneos/gateway/directory/probe[(rparam(\"ImportedConState\")!=\"Suspended\")][(param(\"Imported\")=\"true\")]/managedEntity

Arguments

None

/PROBE:unsuspendImported

Description Unsuspend Imported probes
Long Description Unsuspends importing connection for imported probes
Effect Gateway resumes connection to the exporting gateway that the selected netprobe was imported from, if the connection had been suspended. Suspension may occur due to execution of the "suspend imported probe" command (see above), or automatically by the Data Quality feature of gateway.

Targets

/geneos/gateway/directory/probe[(rparam(\"ImportedConState\")=\"Suspended\")][(param(\"Imported\")=\"true\")]
/geneos/gateway/directory/probe[(rparam(\"ImportedConState\")=\"Suspended\")][(param(\"Imported\")=\"true\")]/managedEntity

Arguments

None

Load Monitoring commands

Load Monitoring commands allow you to start and stop the collection of statistics on demand, write statistics to file, and reset the statistics collected for the gateway.

/LMSTATS:startLMStatsCollectionNow

Path Start the collection of load monitoring statistics
Long Description Tells the gateway to start collecting aggregate statistics such as time spent
Effect Starts load monitoring for aggregate statistics

Targets

/geneos/gateway/directory

Arguments

None

/LMSTATS:startLMStatsCollectionForTimePeriod

Path Enables the collection of load monitoring statistics for a specified time period.
Long Description Tells the gateway to start collecting aggregate statistics, such as time spent, for a specified time period. It stops collecting statistics automatically when the time period elapses.
Effect Enables the collection of load monitoring statistics for a specified time period

Targets

/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
Reset Stats before collection 1 User input: Boolean false
Duration 2 User input: Float 24.00
  3 User input: Options Hours (3600), Minutes (60), Days (86400)
Write Stats to file after collection 4 User input: Boolean false
Reset Stats after collection 5 User input: Boolean false

Mandatory: No

/LMSTATS:stopLMStatsCollection

Path Stop the collection of load monitoring statistics
Long Description Tells the gateway to stop collecting aggregate statistics such as time spent
Effect Stops load monitoring for aggregate statistics so that there is less of a hit on the gateway

Targets

/geneos/gateway/directory

Arguments

None

/LMSTATS:resetLMStats

Path Reset stats
Long Description Tells the gateway to reset the in-memory load monitoring statistics collected so far.
Effect Resets the time based statistics, so that they can be collected again for analysis over a period of time.

Targets

/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
No arguments.

/LMSTATS:writeLMStats

Path Write statistics
Long Description Requests the gateway to write the collected statistics to disk
Effect The gateway writes the available statistics at the point of receiving this command to disk

Targets

/geneos/gateway/directory

Arguments

None

Scheduled Command Data commands

Scheduled Command Data commands allow you to view logs and target status of currently running or last run Scheduled Command.

/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWLOG

Path Shows the Scheduled Command most recent run log.
Long Description Displays the log of the most recent run of the command whose row data-item has been selected. If the command is currently running, this running instance log would be displayed otherwise; the last run instance log (if any) would be displayed.
Effect Views a Scheduled Command run log file. This command allows scope for limiting the amount of data returned.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)

/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:running

Path Shows the targets and command status against each target of currently running command.
Long Description Displays the targets against which the command is running currently. Also displays the status of the command (SUCCESS/FAIL) against each target.
Effect Displays the targets and command status against each target.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname

/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:scheduled

Path Shows the targets against which the command will be run in future
Long Description Displays the targets against which the command is scheduled to run in future.
Effect The target XPath(s) is evaluated at every sample, so the targets can change.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname

/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:last

Path Shows the targets and command status against each target of last run log of command
Long Description Displays the targets against which the command was run most recently in the past. Also displays the status of the command (SUCCESS/FAIL) against each target.
Effect Displays the targets and command status against each target.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname

Scheduled Commands History Data commands

Scheduled Commands History Data commands allow you to view logs and target status of historic runs of Scheduled Command.

/GATEWAY:SCHEDULEDCOMMANDSHISTORYDATA:VIEWLOG

Path Shows the Scheduled Command past run log.
Long Description Displays the past timestamp run log of the command whose row data-item has been selected.
Effect Views a Scheduled Command run log file. This command allows scope for limiting the amount of data returned.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandsHistoryData\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2

/GATEWAY:SCHEDULEDCOMMANDSHISTORYDATA:VIEWTARGETS

Path Shows the targets and command status against each target of past run instance of the command.
Long Description Displays the targets of the past run timestamp of the command whose row DataItem has been selected in the dataview. Also displays the status of the command (SUCCESS/FAIL) against each target.
Effect Displays the targets and command status against each target.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandsHistoryData\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname

Diagnostic commands

The Create diagnostic command will generate a compressed tar file on the gateway machine where the command is run. The tar file will contain information to enable ITRS to diagnose various issue with the gateway. The tar file contains;

  • The environment variables passed into the gateway
  • The gateway setup (including download and history files)
  • Web diagnostic pages
  • The gateway caches (snooze, user assignment, licence, setup, persistence, events)
  • System information (these are gathered by the shell scripts in resources/diagnostics folder. Please see these scripts for more details on what information is gathered

The tar file called "diag-<timestamp>.tar.gz", where timestamp is the unix epoch time value in seconds.

/GATEWAY:createDiagnostics

Path Create Diagnostics
Long Description Creates a compressed tar file containing a set of diagnostic outputs
Effect Obtains a set of data about the gateway and its environment and stores that data in a compressed diagostics tar file.

Targets

/geneos/gateway/directory

Arguments

None

Annotation Commands

Annotation commands are for viewing annotations. Annotations define name / value pairs for Actions and Effects independent of rules and effect configuration, making it possible to place text specific to data items into an email for example.

/ANNOTATIONS/ShowAnnotations

Path Show Annotations
Long Description Show the annotations available
Effect Shows annotations defined for a dataitem. The results are returned in an HTML table.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory

Arguments

None

Rebalance Self-Announcing Netprobes command

/GATEWAY:rebalanceSANs

Description Rebalance Self-Announcing Netprobes
Long Description

Rebalance Self-Announcing Netprobes connected to this Gateway

Effect

This command takes a rebalance criterion and a target value. The criterion is either:

  • Number of Probes — the number of Self-Announcing Netprobes (SANs) to remain on the Gateway.
  • Score — the desired score of the Gateway.

This command removes SANs that are connected to a Gateway to reduce the number of SANs to the target value, or the Gateway score down to the target value. SANs are not removed if the score would be reduced below the target value. For more information, see Score in .

SANs are removed in the order they connected to the Gateway (the newest SAN is removed first, followed by the second newest, and so on). If removing the next SAN in the order would reduce the score below the target value, no further SANs are removed from the Gateway. SANs are not skipped in the order, even if removing an older SAN would reduce the score and keep it above the target value.

This command allows SANs that are removed to find a less busy Gateway to connect to. Therefore, some SANs may return to the Gateway that removed them.

Note: The command may not remove any SANs if the number of SANs if already the target value, or removing a SAN would reduce the Gateway score to below the target value.

The default target value is -1.00 . If this is passed to the command, the command has no effect.

Targets

/geneos/gateway/directory

Arguments

Description Arg Type (Default) Value
Rebalance Criterion 1 User input: Options Number of Probes (numOfProbes), Score (score)
Target Value 2 User input: Float -1.00

Gateway view busiest command

/GATEWAY:MANAGEDENTITYDATA:VIEWBUSIEST

Description View Busiest
Long Description Lists dataviews from those with the most cells to the fewest on a Managed Entity.
Effect Lists cells, rows, sampler, and dataview name of each dataview, in order from the dataview with the most cells to the one with the fewest on the Managed Entity.

Targets

This command is available on the dataviewCount cells of the dataview.

Arguments

Description Arg Type (Default) Value
Managed Entity name 1 XPath ancestor::managedEntity
       

Gateway Hub Data plug-in command

/GATEWAYHUB:ShowDataviews

This command is available on the cells in the following columns in the Gateway Hub data plug-in:

  • Num of dataviews published
  • Num of dataviews unpublished
  • Num of dataviews with errors

The command opens a new window showing a table with the dataviews contributing to the count in that cell.

Description Show Dataviews
Long Description Lists dataviews contributing to the count in the cell.
Effect Shows a table indicating the dataviews contributing to the count in the column, and some information about those dataviews.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param("PluginName")="Gateway-gatewayHubData")]/dataview/rows/row/cell[(@column="Num of dataviews published")]
/geneos/gateway/directory/probe/managedEntity/sampler[(param("PluginName")="Gateway-gatewayHubData")]/dataview/rows/row/cell[(@column="Num of dataviews unpublished")]
/geneos/gateway/directory/probe/managedEntity/sampler[(param("PluginName")="Gateway-gatewayHubData")]/dataview/rows/row/cell[(@column="Num of dataviews with errors")]

Arguments

None

Gateway Hub commands

/GATEWAYHUB:ProposeSchema

This command generates an XML schema definition for headlines and columns not already described in the built-in schema for each dataview in the given sampler.

The command attempts to deduce the data types of columns and headlines from the dataview. Units of measure must be supplied post-generation.

Tables with only two columns are pivoted in the generated XML schema. A comment is included in the XML highlighting this.

Description Propose Schema
Long Description Generates an XML schema definition to paste into dataview schema definition.
Effect Generates an XML schema definition for headlines and columns not already described in an associated schema for each dataview in the given sampler. The command attempts to deduce the data types of columns and headlines from the dataview. Tables with only two columns are pivoted.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity/sampler/dataview

Arguments

None

/GATEWAYHUB:ShowCurrentSchema

Description Show Current Schema
Long Description Shows a table describing the schema defined for each dataview on the sampler.
Effect Shows a table describing the schema defined for each dataview on the sampler. The table combines information from the built-in schema shipped with the Gateway and any additional information added in the GSE.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity/sampler/dataview

Arguments

None

Netprobe commands

Netprobe commands are provided for use with legacy Netprobes which do not export their own commands.

Targets for Netprobe commands

XPath targets for Netprobe commands are modified with the inclusion of certain parameters. This reduces the possible number of command targets when multiple probes are connected to a Gateway. These parameters include:

Note: You can get the full list of commands and command targets for your Gateway setup using the REST service. See REST Service.

Version number in XPath generation

Each plug-in has a group of commands associated with a dataview. This grouping is given a version number. When commands are changed in a plug-in, the version number assigned to the command changes. This version number is used in the XPath for the command.

If multiple different probes are connected to a Gateway, multiple XPaths are generated for the command. A different XPath is generated for each different version number the plug-in exposes.

FKM plug-in

/PLUGIN:FKM:viewTrigger

Path View File Near this Trigger
Long Description View File Near this Trigger
Effect Views an FKM log file near where the selected trigger was detected.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview/rows/row[contains(@name,\"#\")]/cell

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname
  2 Static 0
  3 Static S
  4 Static FileTriggerWatch
  5 Static OR
  6 Static none

/PLUGIN:FKM:viewTriggerWithSize

Path View File Near this Trigger.
Long Description View File Near this Trigger.
Effect Views an FKM log file near where the selected trigger was detected. This is an enhanced version of /PLUGIN:FKM:viewTrigger, allowing the amount of data shown around the trigger to be specified.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler*[(param("PluginName")="FKM")]/dataview[(rparam("ProbeCommandsVersion")="<version>")*]/rows/row[contains(@name,"#")]/cell

Note: For more information on the <version> parameter in the XPath, see Version number in XPath generation.

Arguments

Description Arg Type (Default) Value
  1 XPath @rowname
Download size (kb) 2 User input: Integer 2

/PLUGIN:FKM:triggerDetails

Path Trigger Details.
Long Description Show details of the triggers that have occurred.
Effect

Allows you to see the details of the triggers that have occurred. The resulting output would be as if the user has set the Trigger Mode to Multiple Grouped Trigger.

This option is only available when the Sampler's Trigger Mode has been set to Single Grouped Message.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler*[(param("PluginName")="FKM")]/dataview[(rparam("FKM_GROUP_BY_MSG")="true")][(rparam("ProbeCommandsVersion")="<version>")]*/rows/row[contains(@name,"#")]/cell

Note: For more information on the <version> parameter in the XPath, see Version number in XPath generation.

Arguments

Description Arg Type (Default) Value
1 XPath @rowname

/PLUGIN:FKM:clearTrigger

Path Clear this Trigger
Long Description Clear this Trigger
Effect Removes a detected trigger row from the FKM dataview.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview/rows/row[contains(@name,\"#\")]/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname

/PLUGIN:FKM:viewFile

Path View File
Long Description View File
Effect Views a FKM log file. This command allows scope for filtering the file and limiting the amount of data returned.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview/rows/row[not(contains(@name,\"#\"))]/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
Filter String 4 User input: SingleLineString
5 User input: Options OR, AND
6 User input: SingleLineString

/PLUGIN:FKM:acceptFile

Path Accept this File
Long Description Accept this File
Effect Accepts an FKM file. Clears all detected triggers for this file and removes any additional states (such as file updated) for the file.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname

For more information on using the Accept commands in the Gateway Setup Editor, see Accept files in FKM dataview in File Keyword Monitor (FKM) Plug-in User Guide.

/PLUGIN:FKM:acceptFileMulti

Path Accept files
Long Description Accept multiple files
Effect Accepts multiple FKM files. Clears all detected triggers for each file and removes any additional states (such as file updated).

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
Accept 2 User input: Options this file (THIS), all files (ALL)
Location 3 User input: Options this managedEntity (host) (MANENT), this sampler (SAMPLER), this probe (PROBE), this gateway (all hosts) (GATEWAY).

For more information on using the Accept commands in the Gateway Setup Editor, see Accept files in FKM dataview in File Keyword Monitor (FKM) Plug-in User Guide.

/PLUGIN:FKM:showTables

Path Show Tables
Long Description Shows a summary of the keywords FKM is searching for.
Effect Shows a summary of the keywords FKM is searching for.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview//cell

Arguments

Description Arg Type (Default) Value
1 Static SHOW_TABLES
2 XPath @rowname

FTM plug-in

/PLUGIN:FTM:viewFile

Path View File
Long Description View File
Effect Views a FTM log file. This command allows scope for filtering the file and limiting the amount of data returned.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FTM\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
Filter String 4 User input: SingleLineString
5 User input: Options OR, AND
6 User input: SingleLineString
       

/PLUGIN:FTM:acceptFile

Path Accept File Delay
Long Description Accept File Delay for the selected file
Effect Accept a files delay. Changes delay to zero followed by a comment with the actual delay.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FTM\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname

GL-SLE plug-in

/PLUGIN:GL-SLE:accept

Path Accept
Long Description GL-SLE:Accept Unacked Orders
Effect Removes an unacknowledged order row from the GL-SLE dataview.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"GL-SLE\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static $$$ACCEPT_UNACKED_SLE_ORDERS

PROCESSES plug-in

/PLUGIN:PROCESSES:startWithoutPassword

Path Start Process
Long Description PROCESSES: Start Process
Effect Starts a process using the configured start process script, on a Netprobe which does not require authentication.

Targets

/geneos/gateway/directory/probe[(rparam(\"salt\")=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row[not(contains(@name,\"#\"))]/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
2 Static none

/PLUGIN:PROCESSES:stopWithoutPassword

Path Stop Process
Long Description PROCESSES: Stop Process
Effect Stops a process using the configured stop process script, on a Netprobe which does not require authentication.

Targets

/geneos/gateway/directory/probe[(rparam(\"salt\")=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row[not(contains(@name,\"#\"))]/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
2 Static none
Do not auto-restart 3 User input: Boolean false

/PLUGIN:PROCESSES:startWithPassword

Path Start Process
Long Description PROCESSES: Start Process
Effect Starts a process using the configured start process script, on a Netprobe which requires authentication.

Targets

/geneos/gateway/directory/probe[(rparam(\"salt\")!=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell[not(contains(@rowname,\"#\"))]

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
Enter Password 2 User input: SingleLineString

/PLUGIN:PROCESSES:stopWithPassword

Path Stop Process
Long Description PROCESSES: Stop Process
Effect Stops a process using the configured stop process script, on a Netprobe which requires authentication.

Targets

/geneos/gateway/directory/probe[(rparam(\"salt\")!=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell[not(contains(@rowname,\"#\"))]

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
Enter Password 2 User input: SingleLineString
Do not auto-restart 3 User input: Boolean false

/PLUGIN:PROCESSES:details

Path View details of this Process
Long Description PROCESSES: View details of this Process
Effect Produces a summary of the selected process at the time when the command was executed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static $$$PROCINFO
2 XPath @rowname

/PLUGIN:PROCESSES:log

Path View log file
Long Description PROCESSES: View log file
Effect Views the configured log file for the selected process. This command allows scope for filtering the file and limiting the amount of data returned.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
Filter String 4 User input: SingleLineString
5 User input: Options OR, AND
6 User input: SingleLineString

/PLUGIN:PROCESSES:top20Processes

Path Top 20 Processes
Long Description View Top 20 Processes
Effect isplays a summary for the top 20 processes in order of CPU usage.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]//cell
/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]

Arguments

Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static 20

/PLUGIN:PROCESSES:allProcesses

Path All Processes
Long Description View All Processes
Effect Displays a summary for all processes in order of CPU usage.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]//cell
/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]

Arguments

Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static -1

WTS-SESSIONS plug-in

/PLUGIN:WTS-SESSIONS:viewProcesses

Path View Processes
Long Description WTS-SESSIONS:View Processes
Effect Produces a summary of all terminal services processes at the time when the command was executed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell

Arguments

Description Arg Type (Default) Value
1 Static DETAILS

Mandatory: No

/PLUGIN:WTS-SESSIONS:send

Path Send
Long Description WTS-SESSIONS:Send
Effect Sends the selected user a message.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell

Arguments

Description Arg Type (Default) Value
Enter Message 1 User input: MultiLineString
       

/PLUGIN:WTS-SESSIONS:logoff

Path Logoff
Long Description WTS-SESSIONS:Logoff
Effect Logs off the selected user.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell

Arguments

None

/PLUGIN:WTS-SESSIONS:ping

Path Ping
Long Description WTS-SESSIONS:Ping
Effect Attempts to ping the remote host of the selected user and displays the results.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell

Arguments

Description Arg Type (Default) Value
1 Static PING
       

/PLUGIN:WTS-SESSIONS:tracert

Path Trace route
Long Description WTS-SESSIONS:Trace route
Effect Attempts to trace a route across the network to the remote host of the selected user and displays the results.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell

Arguments

Description Arg Type Default) Value
1 Static TRACERT
       

WTS-PROCESSES plug-in

/PLUGIN:WTS-PROCESSES:killProcess

Path Kill Process
Long Description WTS-PROCESSES:Kill Process
Effect Kills the selected terminal process.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-PROCESSES\")]/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static KILL
       

CITRIX-SESSIONS plug-in

/PLUGIN:CITRIX-SESSIONS:viewProcesses

Path View Processes
Long Description CITRIX-SESSIONS:View Processes
Effect Produces a summary of all Citrix hosted processes at the time when the command was executed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell

Arguments

Description Arg Type (Default) Value
1 Static DETAILS
       

/PLUGIN:CITRIX-SESSIONS:send

Path Send
Long Description CITRIX-SESSIONS:Send
Effect Sends the selected user a message.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell

Arguments

Description Arg Type (Default) Value
Enter Message 1 User input: MultiLineString

/PLUGIN:CITRIX-SESSIONS:logoff

Path Logoff
Long Description CITRIX-SESSIONS:Logoff
Effect Logs off the selected user.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell

Arguments

None

/PLUGIN:CITRIX-SESSIONS:ping

Path Ping
Long Description CITRIX-SESSIONS:Ping
Effect Attempts to ping the remote host of the selected user and displays the results.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell

Arguments

Description Arg Type (Default) Value
1 Static PING

/PLUGIN:CITRIX-SESSIONS:tracert

Path Trace route
Long Description CITRIX-SESSIONS:Trace route
Effect Attempts to trace a route across the network to the remote host of the selected user and displays the results.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell

Arguments

Description Arg Type (Default) Value
1 Static TRACERT

CITRIX-PROCESSES plug-in

/PLUGIN:CITRIX-PROCESSES:killProcess

Path Kill Process
Long Description CITRIX-PROCESSES:Kill Process
Effect Kills the selected terminal process.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-PROCESSES\")]/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static KILL

RMC-INTERFACE plug-in

/PLUGIN:RMC-INTERFACE:setValue

Path Set Value
Long Description RMC-INTERFACE:Set Value
Effect Sets the value of the selected RMC variable.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"RMC-INTERFACE\")]//cell

Arguments

Description Arg Type (Default) Value
1 Static SetValue
Enter Value 2 User input: SingleLineString

/PLUGIN:RMC-INTERFACE:queryValue

Path Query Value
Long Description RMC-INTERFACE:Query Value
Effect Queries the value of the selected RMC variable.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"RMC-INTERFACE\")]//cell

Arguments

Description Arg Type (Default) Value
1 Static QueryValue
Enter Message 2 User input: MultiLineString

LATENCY-RTT plug-in

/PLUGIN:LATENCY-RTT:clearLostMessages

Path Clear
Long Description LATENCY-RTT:Clear Lost Messages
Effect Clears the Lost Messages list in the plug-in

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*LATENCY-RTT*\")]/dataview/headlines/cell[(@name=\"lostMessages\")]

Arguments

None

/PLUGIN:LATENCY-RTT:clearMisdirectedMessages

Path RTT:clearMisdirectedMessages Clear
Long Description LATENCY-RTT:Clear Misdirected Messages
Effect Clears the Misdirected Messages list in the plug-in

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*LATENCY-RTT*\")]/dataview/headlines/cell[(@name=\"misdirectedMessages\")]

Arguments

None

/PLUGIN:LATENCY-RTT:clearCyclicMessages

Path Clear
Long Description LATENCY-RTT:Clear Cyclic Messages
Effect Clears the Cyclic Messages list in the plug-in

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*LATENCY-RTT*\")]/dataview/headlines/cell[(@name=\"cyclicMessages\")]

Arguments

None

HARDWARE plug-in

/PLUGIN:HARDWARE:top20Processes

Path Top 20 Processes
Long Description View Top 20 Processes
Effect Displays a summary for the top 20 processes in order of CPU usage.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")]//cell
/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")]

Arguments

Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static 20

/PLUGIN:HARDWARE:allProcesses

Path All Processes
Long Description View All Processes
Effect Displays a summary for all processes listed in order of CPU usage.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")]//cell
/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")]

Arguments

Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static -1

CPU plug-in

/PLUGIN:CPU:top20Processes

Path Top 20 Processes
Long Description View Top 20 Processes
Effect Displays a summary for the top 20 processes in order of CPU usage.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")]//cell
/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")]

Arguments

Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static 20

/PLUGIN:CPU:allProcesses

Path All Processes
Stderr Type SingleLineString
Effect Displays a summary for all processes listed in order of CPU usage.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")]//cell
/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")]

Arguments

Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static -1

PATS-TRADING-BREACHES plug-in

/PLUGIN:PATS-TRADING-BREACHES:acknowledge

Description Acknowledge
Long Description PATS-TRADING-BREACHES:Acknowledge Breach
Effect Acknowledges a Trading Breach.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"PATS-TRADING-BREACHES*\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static ACKNOWLEDGE
2 XPath @rowname

/PLUGIN:PATS-TRADING-BREACHES:remove

Description Remove
Long Description PATS-TRADING-BREACHES:Remove Breach
Effect Removes a Trading Breach.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"PATS-TRADING-BREACHES*\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static REMOVE
2 XPath @rowname

/PLUGIN:PATS-TRADING-BREACHES:details

Description View Details
Long Description PATS-TRADING-BREACHES:View Details
Effect Shows the details of a Trading Breach.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"PATS-TRADING-BREACHES*\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static REACH_DETAILS
2 XPath @rowname

E4JMS-QUEUES plug-in

/PLUGIN:E4JMS-QUEUES:showMessages

Description Show Messages
Long Description E4JMS-QUEUES:showUsers
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*E4JMS-QUEUES*\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static showUsers
2 XPath @rowname

E4JMS-TOPICS plug-in

/PLUGIN:E4JMS-TOPICS:showUsers

Description Show Users
Long Description E4JMS-TOPICS:showUsers
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*E4JMS-TOPICS*\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static showUsers
2 XPath @rowname

TIB-RV plug-in

/PLUGIN:TIB-RV:acceptError

Description Accept Error
Long Description Accepts an error
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"ERROR\")]/parent::node()/cell

Arguments

Description Arg Type (Default) Value
1 Static ACCEPT_ERROR
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]

/PLUGIN:TIB-RV:acceptWarning

Description Accept Warning
Long Description Accepts a warning
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"WARNING\")]/parent::node()/cell

Arguments

Description Arg Type (Default) Value
1 Static ACCEPT_WARNING
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]

/PLUGIN:TIB-RV:acceptInfo

Description Accept Info
Long Description Accepts an Info
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"INFO\")]/parent::node()/cell

Arguments

Description Arg Type (Default) Value
1 Static ACCEPT_INFO
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]

/PLUGIN:TIB-RV:acceptRvdDown

Description Accept RVD down
Long Description Accepts an RVD down
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"RVD down\")]/parent::node()/cell

Arguments

Description Arg Type (Default) Value
1 Static ACCEPT_RVD_DOWN
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]

WIN-SERVICES plug-in

/PLUGIN:WIN-SERVICES:startService

Description Start Service
Long Description Starts the selected service
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WIN-SERVICES\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
  1 Static START_SERVICE
  2 XPath @rowname

/PLUGIN:WIN-SERVICES:stopService

Description Stop Service
Long Description Stops the selected service
Effect

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WIN-SERVICES\")]/dataview/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 Static STOP_SERVICE
2 XPath @rowname

FLM plug-in

/PLUGIN:FLM:clearFeed

Path Clear all peaks
Long Description Clears all peak latency values for this feed
Effect This command clears (removes) all peak rows which have been created for the selected feed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell

Arguments

Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static CLEAR_FEED
Row name 3 XPath @rowname

/PLUGIN:FLM:clearPeak

Path Clear this peak
Long Description Clears this peak latency value from this feed
Effect This command clears (removes) the selected peak row.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[contains(@name,\"#\")]/cell

Arguments

Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static CLEAR_PEAK
Row name 3 XPath @rowname

/PLUGIN:FLM:verifyFeed

Path Latency report
Long Description Show feed latency for the last X minutes
Effect This command produces an HTML report which displays a period of market data up to 30 minutes, matched against data received from the baseline feed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell

Arguments

Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static REPORT_VERIFY
Row name 3 XPath @rowname
Report interval (minutes) 4 User input: Integer 5
Start Time (optional) 5 User input: SingleLineString HH:MM

/PLUGIN:FLM:verifyFeedPeak

Path Latency report (peak)
Long Description Show feed latency report for the selected peak
Effect This command is issued on a peak row, and produces a similar report to the /PLUGIN:FLM:verifyFeed command. The difference is that rather than the latest X minutes, the resulting report contains (by default) 6 minutes of latency data centred around the time of the tick which produced the peak row (highlighted in red on the report).

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[contains(@name,\"#\")]/cell

Arguments

Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static REPORT_VERIFY_PEAK
Row name 3 XPath @rowname

/PLUGIN:FLM:reportFeed

Path Recent-ticks report
Long Description Report on ticks received in the last X minutes
Effect The recent ticks report command produces an HTML report detailing the ticks received in the last X minutes.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell

Arguments

Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static REPORT_RECENT
Row name 3 XPath @rowname
Report interval (minutes) 4 User input: Integer 5

/PLUGIN:FLM:history

Path Show tick history
Long Description Shows a filtered listing of received tick data
Effect This command displays an output of the FLM tick history file displaying ticks as they are collected from the feeds.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell

Arguments

Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static TICK_HISTORY
Row name 3 XPath @rowname
Initial download size (kb) 4 User input: Integer 10
Delivery Type 5 User input: Options Snapshot (S), Continuous (D)
Feed (use * for wildcards) 6 User input: SingleLineString
Add Baseline Feed 7 User input: Boolean true
Filter (specify 'record.field';use * for wildcards) 8 User input: SingleLineString

Message Tracker plug-in

/PLUGIN:MESSAGE-TRACKER:ClearAll

Path Lost Messages/Clear All
Long Description Clear All Messages
Effect This command will remove all messages from the Lost Messages view and reset the count headline to 0.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]/dataview[@name='Lost']
/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Lost']//cell

Arguments

None

/PLUGIN:MESSAGE-TRACKER:ClearCheckpoint

Path Lost Messages/Clear this Checkpoint
Long Description Clear All Messages for this Checkpoint
Effect This command will remove all lost messages that were last seen at the specified checkpoint.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Lost']/rows/row/cell[@column='lastCheckpointVisited']

Arguments

Description Arg Type (Default) Value
Checkpoint name 1 XPath @value

/PLUGIN:MESSAGE-TRACKER:ClearMessage

Path Lost Messages/Clear Message
Long Description Clear this Message
Effect This command will remove a single message.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Lost']/rows/row/cell

Arguments

Description Arg Type (Default) Value
Row name 1 XPath @rowname
Failure type 2 XPath ../cell[@column='failureType']/@value
Checkpoint name 3 XPath ../cell[@column='lastCheckpointVisited']/@value

/PLUGIN:MESSAGE-TRACKER:ClearAllSlow

Path Slow Messages/Clear All
Long Description Clear All Messages
Effect This command will remove all messages from the Slow Messages view and reset the count headline to 0.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]/dataview[@name='Slow']
/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Slow']//cell

Arguments

Description Arg Type (Default) Value
No arguments

/PLUGIN:MESSAGE-TRACKER:ClearCheckpointSlow

Path Slow Messages/Clear this Checkpoint
Long Description Clear All Messages for this Checkpoint
Effect This command will remove all slow messages that were last seen at the specified checkpoint.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Slow']/rows/row/cell[@column='problemAt']

Arguments

Description Arg Type (Default) Value
Checkpoint name 1 XPath @value

/PLUGIN:MESSAGE-TRACKER:ClearMessageSlow

Path Slow Messages/Clear Message
Long Description Clear this Message
Effect This command will remove a single message.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Slow']/rows/row/cell

Arguments

Description Arg Type (Default) Value
Row name 1 XPath @rowname
Failure type 2 XPath ../cell[@column='failureType']/@value
Checkpoint name 3 XPath ../cell[@column='lastCheckpointVisited']/@value

/PLUGIN:MESSAGE-TRACKER:ClearAllUnacknowledged

Path Unacknowledged Messages/Clear All
Long Description Clear All Messages
Effect This command will remove all messages from the Unacknowledged Messages view.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]/dataview[@name='Unacknowledged']
/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='
Unacknowledged']//cell

Arguments

Description Arg Type (Default) Value
No arguments

/PLUGIN:MESSAGE-TRACKER:ClearCheckpointUnacknowledged

Path Unacknowledged Messages/Clear this Checkpoint
Long Description Clear All Messages for this Checkpoint
Effect This command will remove all unacknowledged messages that were last seen at the specified checkpoint.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Unacknowledged']/rows/row/cell[@column='lastCheckpointVisited']

Arguments

Description Arg Type (Default) Value
Checkpoint name 1 XPath @value

/PLUGIN:MESSAGE-TRACKER:ClearMessageUnacknowledged

Path Unacknowledged Messages/Clear Message
Long Description Clear this Message
Effect This command will remove a single message

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Unacknowledged']/rows/row/cell

Arguments

Description Arg Type (Default) Value
Row name 1 XPath @rowname
Failure type 2 XPath ../cell[@column='failureType']/@value
Checkpoint name 3 XPath ../cell[@column='lastCheckpointVisited']/@value

Sampler commands

/PLUGIN:viewSetup

Description View Setup
Long Description View Setup
Effect Displays the setup for the selected sampler. This command shows both the XML setup, and the legacy converted setup. The encoded password ("AES 256 bit encryption" or "std encoded") are masked and their value is replaced with "xxx". The plaintext password are not masked.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler

Arguments

Description Arg Type (Default) Value
No arguments.

/PLUGIN:lastSampleInfo

Description Last Sample Info
Long Description Last Sample Information
Effect Displays information on when the sampler last sampled.

Targets

/geneos/gateway/directory/probe[(param(\"Virtual\")!=\"true\")]/managedEntity/sampler/dataview

Arguments

Description Arg Type (Default) Value
No arguments.

Netprobe commands

/PROBE:viewLog

Description View Netprobe Log
Long Description View Netprobe Logfile
Effect Views the Netprobe log file (if configured). This command allows scope for filtering the file and limiting the amount of data returned.

Targets

/geneos/gateway/directory/probe[(rparam(\"ConState\")!=\"Down\")]/managedEntity/sampler
/geneos/gateway/directory/probe[(rparam(\"ConState\")!=\"Down\")]/managedEntity

Arguments

Description Arg Type (Default) Value
1 Static $$$NETPROBE_LOG
Initial Download size (bytes) 2 User input: Integer 2000
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
Filter String 4 User input: SingleLineString
5 User input: Options OR, AND
6 User input: SingleLineString

RMS commands

/RMS:putFile

Description Put File
Long Description Puts a file to Netprobe from the Gateway
Effect Copies a file from Gateway to Netprobe using RMS functionality.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
Src Filename (Gateway) 1 User input: SingleLineString
Dst Filename (Probe) 2 User input: SingleLineString

/RMS:getFile

Description Get File
Long Description Gets a file from Netprobe and sends it to the Gateway
Effect Copies a file from Netprobe to Gateway using RMS functionality.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
Src Filename (Probe) 1 User input: SingleLineString
Dst Filename (Gateway) 2 User input: SingleLineString

/RMS:putProbe

Description Put Probe
Long Description Puts a netprobe binary file to Netprobe from the Gateway
Effect Copies a netprobe binary file from Gateway to Netprobe using RMS functionality.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
Src Filename (Gateway) 1 User input: SingleLineString

/RMS:restart

Description Restart
Long Description Restarts the probe
Effect Restarts the Netprobe process.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
1 Static $RESTART

/RMS:rollback

Description Rollback
Long Description Roll back to an old version of the probe
Effect Rolls back an older version of the Netprobe. This is typically used after failure of an /rms/upgrade command to remove the failed upgrade binary.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
1 Static $ROLLBACK

/RMS:upgrade

Description Upgrade
Long Description Prepare the probe for upgrading
Effect Prepares a netprobe for an upgrade by making a backup of the current binary. Used in conjunction with the /rms/rollback command for failed upgrades.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
1 Static $UPGRADE

/RMS:shutdown

Description Shutdown
Long Description Shutdown the probe
Effect Shuts down the probe by exiting the Netprobe process.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
1 Static $SHUTDOWN

/RMS:launch

Description Launch
Long Description Launch a command on the probe
Effect Launches a command on the Netprobe and then returns immediately.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
1 Static $LAUNCH
Command 2 User input: SingleLineString

/RMS:exec

Description Exec
Long Description Exec a command on the probe
Effect Executes a command on the Netprobe and collects the output.

Targets

/geneos/gateway/directory/probe

Arguments

Description Arg Type (Default) Value
Command 1 User input: SingleLineString

Hot Standby Commands

/GATEWAY:failback

Description Manual Failback
Long Description Manual Failback
Effect Releases control to back to the primary gateway in a hot standby pair.

Targets

/geneos/gateway/directory[(param(\"HotStandbyRole\")=\"Secondary\")][(param(\"HotStandbyManualFailbackActive\")=\"true\")][(rparam(\"HotStandbyState\")=\"Active\")]

Arguments

None