Gateway Commands

Commands Copied

Overview Copied

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:

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 Copied

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

Names Copied

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 Copied

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 Active Console. Note:  Beginning Geneos 5.5.x, the Managed Entity display name is used in the user readable paths throughout the Gateway Setup Editor, except when the GSE is opened as a standalone application. This only applies if you open the GSE within the Active Console.

Permissions Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

commands > commandGroup Copied

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 Copied

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 Copied

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 Copied

For configuration of the REST service, see REST Configuration.

commands > gseCommands Copied

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

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 Copied

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:

Mandatory: No

Default: False

commands > requireUserAssignmentComments Copied

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:

Mandatory: No

Default: False

commands > encodedPassword Copied

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 Copied

commands > command Copied

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 Copied

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

Mandatory: Yes

commands > command > targets Copied

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 Copied

An XPath name which describes the data-items that this command applies to. See XPaths - User Guide for more information on XPaths 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 Copied

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

Mandatory: No

Default: A task is configured.

commands > command > task Copied

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

Mandatory: No

Default: A user command is configured.

Command configuration - Advanced tab Copied

commands > command > label Copied

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 Copied

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

Mandatory: No

Default: No description

User Commands Copied

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:

Character limit Copied

The maximum character length for user commands is 10,000.

If a user command fails, then the maximum character length displayed in the output viewer for the combined user command and error message is 1,000. Any characters exceeding this limit are trimmed.

Command arguments Copied

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

commands > command > userCommand > type Copied

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

commands > command > userCommand > runLocation Copied

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 Copied

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 Copied

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 Copied

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 Copied

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:

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

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.
commands > command > userCommand > args > arg > xpath Copied

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:

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

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.
commands > command > userCommand > args > arg > userInput Copied

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:

commands > command > userCommand > args > arg > userinput > description Copied

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 Copied

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

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

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

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

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

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

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

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

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

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

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:

commands > command > userCommand > args > arg > userinput > xPathOptions Copied

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 Copied

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 Copied

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 Copied

A user option.

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

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

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

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 Copied

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 Copied

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 Copied

A name for the environment variable with the usual restrictions for identifiers. Mandatory: Yes

commands > command > userCommand > environmentVariables > value Copied

Value for the environment variable. May include Geneos variable references which are resolved when the command is executed. The value of an environment 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 Copied

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 Copied

A name for the environment variable with the usual restrictions for identifiers. Mandatory: Yes

commands > command > userCommand > secureEnvironmentVariables > value Copied

Value for the environment variable.

commands > command > userCommand > enablePassword Copied

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

Mandatory: No

Default: false

commands > command > userCommand > omitBlankArguments Copied

Optional boolean setting that specifies whether blank arguments passed to the script or the executable file will be omitted. This setting only applies to script commands that are run on either Gateway or Netprobe. If arguments are concatenated and this setting is enabled, the Gateway will check the arguments that are actually passed to the script or the executable file. If a command argument is blank but the result of the concatenation with the other arguments is not blank, the result will still be passed to the script or the executable file.

If this setting is not specified, commands run on either Gateway or Netprobe will not omit blank arguments. Commands run on Active Console will always omit blank arguments.

Mandatory: No

Default: false

Task Commands Copied

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 Copied

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:

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.

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:

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 Copied

commands > command > task Copied

This section contains the configuration for a task command.

Mandatory: Yes

commands > command > task > commands Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

List of target arguments.

Mandatory: Yes

commands > command > task > args > arg > targetArgs > targetArg Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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:

/bin/ls >> tmp.txt

In v4.7, this command fails to execute on both the Gateway and Netprobe: If you would like your arguments to include redirects or pipes, place the arguments into a script and use the script as the executable.

Run Location Version Output
Gateway 4.6 and below Failed to run '/bin/ls >> tmp.txt' Failed to execute '/bin/ls >> tmp.txt' with arguments ''. Exit code: 127 (error executing)
Netprobe 4.6 and below Command executes.
Gateway 4.7 and above Failed to run '/bin/ls >> tmp.txt' Failed to execute '/bin/ls >> tmp.txt' with arguments ''. Exit code: 127 (error executing)
Netprobe 4.7 and above Failed 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.
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"]

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 Copied

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 Copied

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

scheduledCommands > logDirectory Copied

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 Copied

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

scheduledCommands > scheduledCommand Copied

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 Copied

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

scheduledCommands > scheduledCommand > command Copied

Defines the actual command that will be run as scheduled.

scheduledCommands > scheduledCommand > command > commandRef Copied

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

scheduledCommands > scheduledCommand > command > internalCommand Copied

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

scheduledCommands > scheduledCommand > recurrence Copied

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

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 Copied

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 Copied

A secure password type for commands that take password arguments.

scheduledCommands > scheduledCommand > args > arg > targetArgs Copied

Describes the set of arguments that are being overridden.

scheduledCommands > scheduledCommand > args > arg > targetArgs > targetArg Copied

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

scheduledCommands > scheduledCommand > commandPassword Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

scheduledCommands > scheduledCommand > recurrence > pattern > minutes Copied

Recurs on a minutes basis.

scheduledCommands > scheduledCommand > recurrence > pattern > minutes > everyXMinutes Copied

The number of minutes to recur after.

scheduledCommands > scheduledCommand > recurrence > pattern > minutes > activeTime Copied

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

scheduledCommands > scheduledCommand > recurrence > pattern > hours Copied

Recurs on an hourly basis.

scheduledCommands > scheduledCommand > recurrence > pattern > hours > everyXHours Copied

The number of hours to recur after.

scheduledCommands > scheduledCommand > recurrence > pattern > hours > activeTime Copied

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

scheduledCommands > scheduledCommand > recurrence > pattern > days Copied

Recurs on a daily basis.

scheduledCommands > scheduledCommand > recurrence > pattern > days > everyXDays Copied

The number of days after which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > days > everyWeekDay Copied

Recur every weekday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks Copied

Recurs on a weekly basis.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > days Copied

The days that the command should recur.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > everyXWeeks Copied

The number of days after which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > monday Copied

Recur on a Monday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > tuesday Copied

Recur on a Tuesday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > wednesday Copied

Recur on a Wednesday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > thursday Copied

Recur on a Thursday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > friday Copied

Recur on a Friday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > saturday Copied

Recur on a Saturday.

scheduledCommands > scheduledCommand > recurrence > pattern > weeks > Sunday Copied

Recur on a Sunday.

scheduledCommands > scheduledCommand > recurrence > pattern > months Copied

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

scheduledCommands > scheduledCommand > recurrence > pattern > months > everyXMonths Copied

The number of months after which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayXofMonth Copied

The numbered day of the month on which to recur.

scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth Copied

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 Copied

First occurrence in the month.

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

Second occurrence in the month.

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

Third occurrence in the month.

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

Fourth occurrence in the month.

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

Last occurrence in the month.

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

Recur on a Monday.

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

Recur on a Tuesday.

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

Recur on a Wednesday.

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

Recur on a Thursday.

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

Recur on a Friday.

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

Recur on a Saturday.

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

Recur on a week day.

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

Recur on a week-end day.

scheduledCommands > scheduledCommand > recurrence > range Copied

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 Copied

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 Copied

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

scheduledCommands > scheduledCommand > recurrence > range > noEndDate Copied

No end date so continue recurring indefinitely.

scheduledCommands > scheduledCommand > recurrence > range > endAfterXOccurances Copied

Absolute number of runs.

scheduledCommands > scheduledCommand > recurrence > range > endBy Copied

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

REST Service Copied

Aside from running commands via Geneos clients such as Active Console and Web Dashboard, the Gateway can 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:

For all the above URLs:

REST Response Copied

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:

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 Copied

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

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 Copied

The gateway sends command output streams using Server-sent events.

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 Copied

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

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:

Command with no arguments Copied

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 Copied

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 Copied

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;

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 Copied

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 Copied

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 Copied

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 Copied

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 commands. That is, the POST data is a JSON object with the following keys:

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 Copied

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 Copied

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 Copied

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:

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 Copied

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:

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 Copied

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 Copied

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='{ :"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 Copied

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 Copied

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 Copied 

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

Authorise SSO User Copied

Note

This endpoint is not supported when Obcerv is used as the SSO provider. To obtain an SSO token in this case, please see Obtaining an SSO token from Obcerv.

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 Copied 

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

SSO Agent Response Copied 

{
    "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')

Fetch a dataview Copied

The /rest/snapshot/dataview POST endpoint that requires a JSON request to be passed in the POST body. This request should contain a target and optionally a scope.

The response contains a snapshot of the dataview matching the scope specified.

For example:

{
    "target": "//dataview[@name=\"TK1\"]",
    "scope": {
        "value": true,
        "severity": true,
        "snooze": true,
        "user-assignment": true
    }
}

Note

The request target must resolve to a single dataview, otherwise the Gateway rejects the request.

Response Copied

The response is a JSON document that contains something similar to:

{
    "dataview": {
        "timestamp": "2015-07-01T16:18:23.263Z",
        "snoozed": false,
        "snoozed-ancestors": false,
        "headlines": {
            "a": {
                "value": "misc",
                "severity": "CRITICAL",
                "snoozed": true,
                "assigned": true,
                "assigned-to": "Chris"
            },
            "b": {
                "value": "1234514",
                "severity": "UNDEFINED",
                "snoozed": false,
                "assigned": false
            }
        },
        "table-columns": [
            "Row",
            "a",
            "b"
        ],
        "table": {
            "row1": {
                "a": {
                    "value": "string",
                    "severity": "UNDEFINED",
                    "active": false,
                    "snoozed": false,
                    "assigned": false
                },
                "b": {
                    "value": "334",
                    "severity": "UNDEFINED",
                    "snoozed": false,
                    "assigned": false
                }
            },
            "row2": {
                "a": {
                    "value": "another string",
                    "severity": "UNDEFINED",
                    "snoozed": false,
                    "assigned": false
                },
                "b": {
                    "value": "345",
                    "severity": "UNDEFINED",
                    "snoozed": false,
                    "assigned": false
                }
            }
        }
    }
}
Field Description
target Specify an XPATH that resolves to a single dataview.
scope

Specify a list of flags that determine what will be passed back in the dataview snapshot.

The available options are:

  • value — (default) returns the value of each cell.

  • severity —returns the severity of each cell (an active flag will also be returned if a cell is inactive).

  • snooze — returns the snooze state of each cell. This option also returns the snooze state of the dataview itself and a flag snoozed-parents that indicates whether the dataview has any snoozed ancestors.

  • user-assignment — returns the user assignment state of each cell together with the user a cell is assigned to.

HTTP Status codes Copied

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

HTTPS Connections Copied

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 Copied

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. If the SSO provider is SSO Agent or Gateway Hub, this token can be obtained using the Rest service /rest/authorize. However, if the SSO provider is Obcerv, please see Obtaining an SSO token from Obcerv.

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

Obtaining an SSO token from Obcerv Copied

If the SSO provider is Obcerv, an SSO token can be obtained directly from the Obcerv authorization endpoint, using the following curl command:

curl -k -X POST https://obcerv.example.com/auth/realms/obcerv/protocol/openid-connect/token \
  -H "Type: application/x-www-form-urlencoded" -d grant_type=password -d client_id=geneos-ui \
  -d username=theUser -d password=thePassword

The response from Obcerv will be in the following format:

{
    "access_token": "eyJhbGciOiJSUzI1N...",
    "expires_in": 300,
    ...
    "token_type": "Bearer ..."
}

To save parsing the SSO token out of the response, if you have installed the jq utility you can use a command line like this:

SSO_TOKEN=$( \
curl -k -X POST https://obcerv.example.com/auth/realms/obcerv/protocol/openid-connect/token \
  -H "Type: application/x-www-form-urlencoded" -d grant_type=password -d client_id=geneos-ui \
  -d username=cdavies -d password=cdavies | jq -r '.access_token')

Configuration Copied

commands > restService Copied

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 Copied

Boolean value controlling whether REST service is enabled or not.

Mandatory: No

Default: false

commands > restService > allowOnInsecureComms Copied

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 Copied

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 Copied

Introduction Copied

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 Copied

System commands are commands which allow control of the system.

Snooze commands Copied

Snooze commands allow control over the gateway snooze functionality.

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:

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

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

Targets

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

Arguments

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.

Snooze until command Copied

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

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: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 (optionallyto 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 Value (Unused)
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 Copied

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

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

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

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

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 Copied

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 :

showVariablesExample

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 Copied

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 Copied

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 Copied

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 Copied

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

Netprobe commands Copied

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

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.

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

Collection Agent commands Copied

/GATEWAY:PROBESDATA:viewNetprobeLog

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/managedEntity/sampler[(param("PluginName")="Gateway-probeData")]/dataview[(@name!="Collection Agents")]/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
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

/GATEWAY:PROBESDATA:viewCALog

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

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param("PluginName")="Gateway-probeData")]/dataview[(@name="Collection Agents")]/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 XPath @rowname
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

/GATEWAY:PROBESDATA:viewCAConfig

Description View Configuration
Long Description View Collection Agent Configuration
Effect Views the Collection Agent log file (if the Collection Agent is managed by the Netprobe).

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param("PluginName")="Gateway-probeData")]/dataview[(@name="Collection Agents")]/rows/row/cell

Arguments

Description Arg Type (Default) Value
1 XPath: @rowname
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

/GATEWAY:PROBESDATA:viewCAError

Description View Error
Long Description View Collection Agent Error
Effect Views any errors returned when trying to start the Collection Agent.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param("PluginName")="Gateway-probeData")]/dataview[(@name="Collection Agents")]/rows/row/cell[(@column="status")]

Arguments

Description Arg Type (Default) Value
1 XPath @rowname

Gateway Sharing commands Copied

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

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 Copied

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 Copied

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 Copied

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 tar file called “diag-.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 Copied

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 Copied

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

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 Copied

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

/GATEWAYHUB:ShowDataviews

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.

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

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

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 Copied

/GATEWAYHUB:ProposeSchema

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.

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.

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

Obcerv commands Copied

/OBCERV:VIEW_METRICS_DROPPED_ISSUES
Description Show metric issues dropped.
Long Description Show a table describing which schema-defined metrics have a type mismatch.
Effect Show a table of data collected by the Gateway when there is a metric type mismatch when publishing to Obcerv.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-obcervConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsDropped")]/cell[(@column="value")]

Arguments

None

/OBCERV:VIEW_METRICS_CHANGED_ISSUES
Description Show metric issues changed.
Long Description Show a table describing which (schemaless) metrics type have a type mismatch from the last type published to Obcerv.
Effect Shows a table of data collected by the Gateway when there is a metric type change when publishing to Obcerv.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-obcervConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsChanged")]/cell[(@column="value")]

Arguments

None

/OBCERV:CLEAR_METRICS_DROPPED_ISSUES
Description Clear list of metrics issues dropped.
Long Description Clear list of metrics issues dropped.
Effect Clear the list of dropped metrics issues. This allows for new issues to be added to the list, assuming the previous ones were fixed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-obcervConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsDropped")]/cell[(@column="value")]

Arguments

None

/OBCERV:CLEAR_METRICS_CHANGED_ISSUES
Description Clear list of metrics issues changed.
Long Description Clear list of metrics issues changed.
Effect Clear the list of changed metrics issues. This allows for new issues to be added to the list, assuming the previous ones were fixed.

Targets

/geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-obcervConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsChanged")]/cell[(@column="value")]

Arguments

None

Netprobe commands Copied

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

Targets for Netprobe commands Copied

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 Copied

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.

Control-M plugin Copied

/PLUGIN:CONTROL-M:waitingInfo Copied
Path Show Waiting Info
Long Description Show Waiting Info
Effect Shows the reason for why a job in waiting has not been executed yet.
Targets Copied 
/geneos/gateway/directory/probe/managedEntity/sampler[param("PluginName")="CONTROL-M"]/dataview/rows/row/cell
Arguments Copied
Description Arg Type (Default) Value
1 XPath @rowname

FKM plug-in Copied

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

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

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

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

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

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

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

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

Beginning Geneos 5.1.1, internal commands for the RMC Interface plugin have been removed and are no longer supported.

LATENCY-RTT plug-in Copied

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

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

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

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

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

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

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

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

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

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

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

/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
/geneos/gateway/directory/probe[(rparam("ConState")!="Down")]

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

/PROBE:viewCALog

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

Targets

/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]
/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]/managedEntity[(param("Dynamic")="true")]
/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]/managedEntity/sampler[(param("PluginName")="DYNAMIC-ENTITIES-HEALTH")]
/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]/managedEntity/sampler[(param("PluginName")="DYNAMIC-ENTITIES-HEALTH")]/dataview

Arguments

Description Arg Type (Default) Value
1 Static @rowname
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

/PROBE:viewCAConfig

Description View Configuration
Long Description View Collection Agent Configuration
Effect Views the Collection Agent log file (if the Collection Agent is managed by the Netprobe).

Targets

/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]
/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]/managedEntity[(param("Dynamic")="true")]
/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]/managedEntity/sampler[(param("PluginName")="DYNAMIC-ENTITIES-HEALTH")]
/geneos/gateway/directory/probe[(param("CollectionAgentManager")="true")][(rparam("ConState")!="Down")]/managedEntity/sampler[(param("PluginName")="DYNAMIC-ENTITIES-HEALTH")]/dataview

Arguments

Description Arg Type (Default) Value
1 Static $$$COLLECTION_AGENT_CONFIG
Initial Download size (bytes) 2 Static: Integer 1024
Delivery Type 3 Static S
Filter String 4 Static
5 Static OR
6 Static

RMS commands Copied

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

/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

["Geneos"] ["Geneos > Gateway"] ["User Guide"]

Was this topic helpful?