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:
- Internal Gateway commands. These are commands that affect the internal operations of gateway. For instance, the gateway snooze functionality can be controlled by internal commands.
- Internal Plug-In commands. These commands allow users to affect the operation of a specific plug-in running on a Netprobe process. These have special meanings which are understood by a plug-in and may affect the monitoring data that plug-in produces. E.g. the “View file” command for the FKM plug-in.
- User commands. These are commands defined by users in the gateway setup, which can run external scripts, executables or shared library functions.
- Tasks commands allow users to group multiple commands together so they will run sequentially in the order they are defined in the task.
Gateway and Plug-In commands are defined by the Netprobes and Gateways versions that are currently being used in the system. User and Task commands are defined by Geneos administrators so the configuration options described in this section concerns these types.
Common Command Settings 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:
enableProposeSchema
— enabled by default.
Note
Propose Schema command in the GSE runs against all instances of the named sampler on the Gateway. This may not be desirable on production a Gateway.
commands > requireSnoozeComments 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:
- Active Console v4.10.0 and newer enforce the input of comments on commands.
- Active Console v4.9.0 and older do not enforce the input of comments on commands. Instead, these AC2s pass commands that require comments to the Gateway. The Gateway returns an error if there is no comment included in the command parameters.
- If the Active Console goes through one Gateway that does not enforce comments, to reach another Gateway that does, the Active Console passes the command to the Gateway. If there is no comment, Gateway returns an error.
Mandatory: No
Default: False
commands > requireUserAssignmentComments 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:
- Active Console v4.10.0 and newer enforce the input of comments on commands.
- Active Console v4.9.0 and older do not enforce the input of comments on commands. Instead, these AC2s pass commands that require comments to the Gateway. The Gateway returns an error if there is no comment included in the command parameters.
- If the Active Console goes through one Gateway that does not enforce comments, to reach another Gateway that does, the Active Console passes the command to the Gateway. If there is no comment, Gateway returns an error.
Mandatory: No
Default: False
commands > encodedPassword 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 - fixed arguments which do not change.
- Text arguments - combination of fixed + Geneos variable arguments; the value of which is evaluated based on the execution data-item environment.
- XPath arguments - evaluated arguments which change based on the execution data-item.
- User-input arguments - these arguments are provided by the user at execution.
Static arguments are the easiest to configure, as they consist of a simple string. This string will be passed to the command every time it is executed - the value cannot change unless users modify the gateway setup.
Text arguments can be specified as a combination of fixed text and Geneos variables. The Geneos variables values are evaluated according to the execution data-item environment. XPath arguments are specified as an XPath, which is evaluated by the client (e.g. ActiveConsole 2) when the command is executed, without the need for user interaction. The path is evaluated relative to the target data-item the command has been run on, and so is best used to extract the value of the data-item, or other nearby data-items. See XPaths - User Guide for more information on XPaths.
User-input arguments are the most common type of argument as they provide the most flexibility in a command. When a user attempts to execute a command containing user-input arguments, a dialog will appear on the client (e.g. ActiveConsole 2) prompting the user to fill in values for these arguments. This prompt will also describe the argument requested and additionally contain default values which the user can choose to override.
Configuration 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="MNL_PUGO_GATEWAY_9370")]/directory/probe[(@name="LORO_6370")]/managedEntity[(@name="LORO")]</target>
</targets>
<userCommand>
<type>script</type>
<runLocation>netprobe</runLocation>
<args>
<arg>
<static>powershell.exe -executionpolicy bypass -file "D:\_tickets\Scripts\hello world.ps1"</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:
- boolean
- float
- integer
- singleLineString
- multiLineString
- options
- timeInSeconds
- xpathOptions
- password
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:
- Now — changes the field to the current time.
- None — empties the field. This resets the time to default.
- OK — the field changes to the time specified in the calendar.
commands > command > userCommand > args > arg > userinput > xPathOptions 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.
stdAES
- AES 256-bit encryption. The password is entered in the Set password… box.var
- a reference to a variable that provides a password in Operating Environment. References to invalid variables are ignored. See Decode encrypted environment variables for details on how to decrypt these.
commands > command > userCommand > enablePassword Copied
This option has a different effect depending on the Run location:
Client
— No effect. The option is ignored.Gateway
— User is asked to enter the Gateway Command Password.Netprobe
— User is asked to enter the Netprobe password.
Mandatory: No
Default: false
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 locationClient
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:
- Take each command in turn in the order specified by the task.
- Take each argument from the command numbering from 1.
- If the argument is a user input check for a target argument replacement. Add this command to your list if you haven’t added it before.
- If a targeted argument is followed by concatenate arguments add those and continue numbering if you haven’t added them already.
At the end of this you will have a list of arguments that are unique from the task but may have some duplication from arguments taken directly from commands. Any user input arguments left in your list are the arguments you must target and their argument number for the task.
Note
Netprobe commands are generally not published at the time the setup is validated and applied (the applied setup then having to be applied to the connected probes).
Probe commands are validated and arguments substituted when the task is executed.
This may result in error messages in the Gateway and execution logs if the arguments are mis-configured.
Configuration 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:
-
Each argument is passed exactly as written, including spaces, quotes, and backslashes. There are no escape characters. For example, the output from the command below produces unexpected results prior to version 4.7:
This command prints each argument encased in square brackets and on a new line. In v4.6 and below, this command produces unexpected behaviour. In v4.7, the behaviour is now consistent between the Gateway and the Netprobe and takes each arguments exactly as written:
-
The first argument in a command must either be an executable or a path to an executable (such as a script). Otherwise, the command will fail to execute. This behaviour was inconsistent between Netprobe and Gateway prior to v4.7. For example, the command below would run on the Netprobe but fail on the Gateway:
/bin/ls >> tmp.txt
In v4.7, this command fails to execute on both the Gateway and Netprobe: 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 |
Failed to run '/bin/ls >> tmp.txt' Failed to execute '/bin/ls >> tmp.txt' with arguments ''. Exit code: 127 (error executing) |
Netprobe | 4.7 |
Failed to run executable '/bin/ls >> tmp.txt' with arguments '' () |
- Any empty arguments are passed as blank strings and are not removed from the command.
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
- 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.
- If you would like to have the new behaviour on the Gateway, then you need to upgrade the Gateway to at least v4.7.
- 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.
- Select the Scheduled commands top-level section. If this section does not exist, double-click to create it.
- Select the New Scheduled Command button to create a new scheduled command.
- Set a name for your scheduled command, link it to the command it needs to run and also, specify the target of the command.
- Ensure the Advanced tab is visible and select the “Add new” option. This brings up a dialog.
- 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:
- In the GSE, click Commands.
- Select the Advanced tab.
- In Rest service, tick the box next to Enabled.
The Gateway REST service supports the following URLs:
<protocol>://<host>:<port>/rest/runCommand
to run a command. The command to run, the target to run it against, and any required arguments are provided in a JSON data package. See Run commands.<protocol>://<host>:<port>/rest/commands/all
to list all commands known to the Gateway (except for any commands that are configured to run on the Active Console client.) No additional data is required for this type of request. See List all commands.<protocol>://<host>:<port>/rest/commands/available
to list the commands available on a given target. The target and, optionally, a pattern to be matched against the command name are provided in a JSON data package. See List available commands.<protocol>://<host>:<port>/rest/setup/validate
to obtain a report listing validation issues for the Gateway setup. No additional data is required for this type of request. See Validate the Gateway setup.<protocol>://<host>:<port>/rest/gatewayinfo/timezone
to obtain the Gateway time zone and the offset from UTC. See Obtain the Gateway time zone and offset.<protocol>://<host>:<port>/rest/authorize
to obtain an SSO Token. This token can be used to run other REST commands as the authorized user. See Authorise SSO User.<protocol>://<host>:<port>/liveness
to check the liveness of the component. If the component is alive, this will return a200
code. Otherwise, it will return a503
code and will restart the container running the component.<protocol>://<host>:<port>/rest/snapshot/dataview
to fetch a specified dataview’s values, severity status, and snooze status. See Fetch dataviews.
For all the above URLs:
host
- host of the Gateway.port
- secure listen port of the Gateway. The insecure listen port can also be used, If the Gateway administrator permits this via the Gateway Setup Editor.protocol
- if the port is secure, then thehttps
protocol is used. Otherwise, thehttp
protocol is used.
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:
- application/json
- text/event-stream
If the REST client requests the service use application/json to return its data then a JSON Response document will be returned. If the REST client requests the service use text/event-stream to return its data then a command output stream will be returned using the Server-sent events protocol.
Currently if there is no match available for any of the requested document types, the REST Service will send a JSON Response document.
JSON Response document Copied
The JSON response document contains some/all of the following fields:
- mimetype [Optional] - Specifies the mimetype of the data streams that have been sent as part of the response. Currently the Gateway supports 2 mimetypes: (“text/plain”, “text/html”). The mimetypes for the streams are dependant on the command that has been run. This is an array as different streams can have different mimetypes.
- status [Required] - The status of the command. This is either “finished” or “error”
- streamdata [Optional] - An array of data sent to different ouput streams. The streams currently supported are: + stdout - Output stream, where normal output from a command is placed + stderr - Error stream, where error output form a command is placed + execLog - Information about what external command the gateway/netprobe executed is placed in this stream
The data from the streams can be inter-mingled. Each entry in the “streamdata” array is a JSON item with a field name that matched one of the stream names and a value that contains the data sent to that stream. The items are ordered in the array in chronological order.
The JSON response document is composed once the command has finished. For Streaming commands, or long running commands where the output needs to be examined before the command has finished, this return type should not be used.
Once the message has been sent, the gateway will close the connection to the REST client.
If an error occurs when running the command then the appropriate HTTP status error will be returned. The error codes that the REST service can return are detailed in section HTTP Status codes.
Command output stream 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:
- 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).
- 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.
- 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
- command [Required] : Name of the command that the REST client requires the gateway to run
- target [Required] : XPath name that identifies the location in the gateway directory where the command should be run. The xpath need not be the full unique name of an item, but must unambiguously identify a single data item. The unique name of an item can be obtained by selecting ‘Copy From … > Path’ on the menu attached to each data item. (see Target names and relative paths).
- args [Optional] : Arguments required by the command. Each command is has a number of arguments. The arguments for internal commands are defined in Internal Commands. The arguments for user defined commands are the arguments list defined in Command arguments. Each argument has an index number and the JSON structure of the arguments is a map from the argument number to the value supplied for that argument.
The format of the REST service response can be controlled using HTTP content negotiation. See section REST Response.
This section contains a number of examples of using curl to run commands using the REST API. In all these examples the following assumptions are made:
- Curl is run on the gateway machine
- The REST service is configured to service both secure and insecure connections
- The gateway is listening insecurely on port 7039
- Gateway name is GW
- Probe name is P
- Managed Entity name is ME
- There is a user command cmd1 that prints “Hello World”
Command with no arguments 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;
- User Comment : This is a text field that the user sets to remind themselves of why the snooze was applied.
- Severity : This is an Xpath argument that is normally filled by the Geneos client. In this case it is expected to contain the value of the current severity. The REST client does not need to set this value as the gateway will look up the value from using the xpath and the target. However the REST client can pass a value that will override this value. (It may do this if it wishes to indicate the severity it was working with at the time the command was run).
- Static value “severityTo”. This should never be set by the REST client. The REST Service does not allow static values to be changed.
- Target Severity : This is the Severity the Gateway will watch for. When the target changes to this severity the gateway will unsnooze the command target. This value is a severity and so should be an integer between 0 and 3.
For our example we will Snooze Managed Entity ME until the severity goes to ‘OK’ (value 1). We know that currently the severity of the Managed Entity is ‘Critical’ (value 3) so will inform the gateway of this fact.
Curl Command
curl -X POST -s --data \
'{
"command": "/SNOOZE:severityTo",
"target": "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]",
"args": {
"1": "Remedial work in progress",
"2": 3,
"4": 1
}
}' \
http://localhost:7039/rest/runCommand
Gateway Response
{
"status": "finished"
}
User defined Command 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:
- target [Required] : XPath name that identifies the location in the gateway directory for which available commands should be listed. This target must match a single data item: the xpath should be the unique name of that data item. The unique name of an item can be obtained by selecting ‘Copy From … > Path’ on the menu attached to each data item. (See Target names and relative paths).
- namePattern [Optional] : Regular expression (using PCRE syntax) to be matched against command names. Only commands whose names match this pattern will be selected.
Example usage (assuming the probe was snoozed, this would list the /SNOOZE:info
and /SNOOZE:manual
commands):
curl -X POST -s --data \
'{
"target": "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]",
"namePattern": "^/SNOOZE:[mi]"
}' \
http://localhost:7039/rest/commands/available
If user authentication is enabled, this endpoint will list only the commands which are available to the user whose credentials are provided in the request.
JSON command list response 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:
- target [Required] : XPath name selecting the data items to list. This path will be evaluated against the whole directory of data items known to the Gateway.
- limit [Optional] : Integer value to override the default limit of 100 items. By default, if the target path matches more than 100 items, the request will be rejected. Note that attempting to retrieve a very large number of XPaths will force the Gateway to allocate a very large amount of memory to service the request, which may harm its performance.
Example usage, listing all managed entities (assuming that there are fewer than 100):
curl -X GET -o cmdresult.json -s --data '{ "target":"//managedEntity" }' http://localhost:7039/rest/xpaths/match
Note
This endpoint will not take permissions into account. If authentication is enabled, it is available to any authenticated user.
Items which are targets for a given command 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:
- target [Required] : XPath name selecting the data items to check as targets of the command. This path will be evaluated against the whole directory of data items known to the Gateway.
- command [Required] : Name of the command against which to check the data items matching the target XPath.
- limit [Optional] : Integer value to override the default limit of 100 items. By default, if the path matches more than 100 items (regardless of whether they are valid targets for the command), the request will be rejected. Note that attempting to check a very large number of data items will force the Gateway to allocate a very large amount of memory to service the request, which may harm its performance.
Example usage, listing all managed entities which can be unsnoozed (assuming that there are fewer than 100 managed entities in total):
curl -X GET -o cmdresult.json -s --data \
'{ "target":"//managedEntity", "command":"/SNOOZE:unsnooze" }' \
http://localhost:7039/rest/xpaths/commandTargets
If user authentication is enabled, this endpoint will list only the items for which the requesting user can run the command.
JSON XPath list response 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:
- The time zone specified in the operatingEnvironment > timezone configuration setting.
- The value of the
TZ
environment variable. - (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:
|
HTTP Status codes Copied
The following HTTP error codes will be returned if the REST service encounters an error:
- OK (200): This will be returned if the REST service runs the command successfully.
- Bad Request (400): This will be returned if the POST data is not well-formed JSON or if a mandatory item is missing.
- Forbidden (403): This will be returned if the user provides invalid credentials (and credentials are required). It will also be returned if the user’s credentials are correct but the user does not have permission to run the command requested on the target requested.
- Not Found (404): This will be returned if the service is not available. It can occur if the gateway is not running a REST service. It can also occur if the REST service is secure but the request is made on the gateway’s insecure port.
- Internal Server Error (500): This will be returned if the command run returns an error.
HTTPS Connections 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:
- The item is snoozed ‘until severity changes’ when the severity is OK, Warning or Critical.
- The host gateway or the source of data (netprobe or gateway) is restarted.
- The severity of the item is recalculated as ‘undefined’ after the restart.
Because data items are created with undefined severity and the unsnoozing mechanism depends on detecting a change in severity, the item remains snoozed.
If the item were to be automatically unsnoozed in this scenario, it would also be (wrongly) unsnoozed even if its severity was about to be reset to the previous value (such as Critical) by a rule.
In general, ITRS recommends that the severity of a data item should not be explicitly set to undefined by a rule.
/SNOOZE:manual
Path | Snooze/Manual |
Long Description | Snooze until manually unsnoozed |
Effect | Snoozes a data-item until manually
unsnoozed by a user using the /SNOOZE:unsnooze
command. |
Targets
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory
Arguments
Description | Arg | Type | (Default) Value |
---|---|---|---|
User comment | 1 | User input: MultiLineString | |
2 | XPath | state/@severity | |
3 | Static | manual | |
4 | Static | 0 |
/SNOOZE:manualAllMe
Path | Snooze/Manual |
Long Description | Snooze until manually unsnoozed with options to snooze on all managedEntities. |
Effect | Snoozes a data-item until manually
unsnoozed by a user using the /SNOOZE:unsnooze
command. |
Targets
/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
Arguments
Description | Arg | Type | (Default) Value |
---|---|---|---|
User comment | 1 | User input: MultiLineString | |
2 | XPath | state/@severity | |
3 | Static | manual | |
4 | Static | 0 | |
All ManagedEntities | 5 | User input: Options |
|
/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 |
|
/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 |
|
/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 |
|
/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 |
|
|
All ManagedEntities | 6 | User input: Options |
|
/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 |
|
/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 |
|
/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:until
command is a generic command which snoozes a DataItem until one of the following four conditions are met:
- Value Change (only applicable for
/SNOOZE:untilAllMeCell
) - Severity Change (either SeverityFrom or SeverityTo one of Critical/Warning/Undefined/Ok)
- Time Period (n * Hours/Minutes/Days)
- Date/Time (Optional Date and Time)
A checkbox is provided to tick a particular condition to be included for Snooze until command. If none of the above conditions are ticked, then the data item is not snoozed and error is reported. If both Time Period and Date / Time is ticked with valid values, then the DataItem is snoozed until the earliest time (Time vs Date /Time) is reached.
The Time argument can also optionally include the time zone region in the form HH:MM timezoneRegion
(for example, 14:20 Europe/London). If a time zone region is not provided, the Gateway’s time zone will be used.
The list of supported time zone regions is found in the date_time_zonespec.csv
file in the Gateway /resources
directory, provided as part of the Gateway bundle (see Time Zones and Time Formats for more information).
There are 3 versions of /SNOOZE:until
command:
/SNOOZE:until
which applies to directory, probe and managedEntity data-items./SNOOZE:untilAllMe
which applies to sampler and dataview./SNOOZE:untilAllMeCell
which applies to cell data-items.
/SNOOZE:untilAllMe
and /SNOOZE:untilAllMeCell
commands have additional parameter which allows the command to be run on a single managedEntity or multiple managedEntities matching by sampler or plug-in.
/SNOOZE:until
Path | Snooze/Until Severity/Time/ Date /Time |
Long Description | Snooze until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached |
Effect | Snoozes a data-item until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached |
Targets
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory
Arguments
Description | Arg | Type | (Default) Value |
---|---|---|---|
User comment | 1 | User input: MultiLineString | |
2 | XPath | state/@severity | |
3 | Static | until | |
Value | 4 | Static | Value (Unused) |
5 | Static | 0 (Unused) | |
Severity | 6 | User input: Boolean | false |
7 | User input: Options | severityFrom (0), severityTo(1) | |
Target severity | 8 | User input: Integer | 1 |
Time | 9 | User input: Boolean | false |
Duration | 10 | User input: Float | 24 |
11 | User input: Options |
|
|
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 |
|
|
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 |
|
/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 |
|
|
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 |
|
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 |
|
/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:
To view the path, hover over the name of the path alias. |
Targets
/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory
Arguments
Description | Arg | Type | (Default) Value |
---|---|---|---|
Output format version | 1 | XPath | /geneos/client/features/@RuleShowEx |
/RULES:showVariables
Path | Show Variables |
Long Description | Get information about the variables available on command target |
Effect | Displays information about the configured variables available on a target. The command shows the name, type, value, source (either main setup or include file name) and path to where it's configured. Variable values are displayed in a JSON like format to make reading of complex variables easier. For example : All of the macros available at that level of the directory hierachy are shown. These are values that the gateway will fill in for you when used as the value of a variable. Variables defined as a macro are a special given that the Gateway replaces the macro name with a constant. As such there's no meta-data associated with the variable and it isn't possible to show the source or setup path. This isn't such a great issue as the value will be the same no-matter where you define it. |
Targets
/geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory
Arguments
None
/RULES:ShowRuleContention
Path | Show Rule Contention |
Long Description | Shows rule targets with more than one rule which may be the cause of rule contention. |
Effect | Displays a list of rule targets for which there is more than one rule, which can cause rule contention. For each target the rule definition path and file in which it is defined is shown. The target is broken down into a simplified user readable xpath as per the path editor of active console. e.g. gateway/probe/sampler(type=")/dataview/row/column |
Targets
/geneos/gateway/directory/probe/managedEntity/sampler/dataview
/geneos/gateway/directory/probe/managedEntity/sampler
/geneos/gateway/directory/probe/managedEntity
/geneos/gateway/directory/probe
/geneos/gateway/directory
Arguments
None
Sampler commands 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.
|
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 environment variables passed into the gateway
- The gateway setup (including download and history files)
- Web diagnostic pages
- The gateway caches (snooze, user assignment, licence, setup, persistence, events)
- System information (these are gathered by the shell scripts in resources/diagnostics folder. Please see these scripts for more details on what information is gathered
The tar file called “diag-
/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:
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. 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:
- Num of dataviews published
- Num of dataviews unpublished
- Num of dataviews with errors
The command opens a new window showing a table with the dataviews contributing to the count in that cell.
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
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:
- The command version number. See Version number in XPath generation.
- If the command is published.
- If the command is from an imported Gateway.
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