--- title: "Gateway Commands" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/monitoring-and-alerts/geneos_commands_tr/index.html" ---## Commands ### Overview Gateway commands are the primary method of interaction between the Gateway and connected users. Commands are invoked by users through a controlling process (such as Active Console) which prompts the Gateway to perform a given operation. There are several types of command: - **Internal Gateway commands.** These are commands that affect the internal operations of gateway. For instance, the gateway snooze functionality can be controlled by internal commands. - **Internal Plug-In commands.** These commands allow users to affect the operation of a specific plug-in running on a Netprobe process. These have special meanings which are understood by a plug-in and may affect the monitoring data that plug-in produces. E.g. the "View file" command for the FKM plug-in. - **User commands.** These are commands defined by users in the gateway setup, which can run external scripts, executables or shared library functions. - **Tasks commands** allow users to group multiple commands together so they will run sequentially in the order they are defined in the task. Gateway and Plug-In commands are defined by the Netprobes and Gateways versions that are currently being used in the system. User and Task commands are defined by Geneos administrators so the configuration options described in this section concerns these types. ### Common Command Settings This section describes settings common to both user and task commands. #### Names Commands are defined in the command section as a list of named `command` nodes. As commands are referenced by name in other parts of the gateway setup, each command must have a unique name among all other command definitions. #### Targets The target of a command defines the set of data-items that the command will run against and are defined using an XPath (see the [XPath User Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html) for more information on XPaths; in particular, the [Commands - Useful Targets](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html#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 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/security/access-controls/geneos_authentication_tr/index.html#command-permissions). #### Displaying Commands By default a command will be displayed to the user by its unique name. The 'label' setting on a command or command group can be used to override the name that will be presented to the user. For example, the following command configuration (1): ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-setup.png) Results in the command being displayed as: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-display-new-command.png) #### Grouping Commands Commands can be logically grouped into commandGroups in the setup editor. This can be used to for purely organisational purposes within the setup file or to create sub menus that will be presented to the user. To create organisational groups, create named commandGroups within the setup editor. Commands can then be created or dragged into these. E.g. Group1, Group2 and Group3 (2): ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-group.png) 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: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-group-display.png) ### Configuration User-defined commands are configured inside the commands top-level section. This section contains a list of `command` nodes, each of which defines a single command. The commands must be uniquely named, and have special meaning as described [above](#common-command-settings). ##### commands The command top-level section holds the gateway user-defined command configuration. This section can contain any number of command definitions. ##### commands > commandGroup Logically groups a set of commands in the setup editor. This can be used for purely organisational purposes within the setup file or to create sub menus that will be presented to the user. ##### commands > commandGroup > menu Causes the commands under the commandGroup to be presented to the user under a sub-menu. Mandatory: No Default: (no sub-menu is not created) ##### commands > commandGroup > menu > label Defines the name given to sub-menu created for the command group. Mandatory: No Default: (the name of the command group) #### Commands top-level configuration - Advanced tab For configuration of the REST service, see [REST Configuration.](#configuration-4) ##### commands > gseCommands Presents a drop-down menu that allows you to enable or disable certain GSE commands: - `enableProposeSchema` — enabled by default. **Note** [Propose Schema](#gateway-hub-commands) command in the GSE runs against all instances of the named sampler on the Gateway. This may not be desirable on production a Gateway. ##### commands > requireSnoozeComments Specifies that snooze commands require comments to be entered to execute the command. This includes the **Unsnooze** command. Comments are logged and/or published to the database if enabled on the Gateway. This affects commands run from Active Console, through REST, or through Gateway sharing. The enforcement of this depends on the command target and Active Console version: - Active Console v4.10.0 and newer enforce the input of comments on commands. - Active Console v4.9.0 and older do not enforce the input of comments on commands. Instead, these AC2s pass commands that require comments to the Gateway. The Gateway returns an error if there is no comment included in the command parameters. - If the Active Console goes through one Gateway that does not enforce comments, to reach another Gateway that does, the Active Console passes the command to the Gateway. If there is no comment, Gateway returns an error. Mandatory: No Default: False ##### commands > requireUserAssignmentComments Specifies that user assignment commands require comments to be entered to execute the command. This includes the **Unassign** command. Comments are logged and/or published to the database if enabled on the Gateway. This affects commands run from Active Console, through REST, or through Gateway sharing. The enforcement of this depends on the command target and Active Console version: - Active Console v4.10.0 and newer enforce the input of comments on commands. - Active Console v4.9.0 and older do not enforce the input of comments on commands. Instead, these AC2s pass commands that require comments to the Gateway. The Gateway returns an error if there is no comment included in the command parameters. - If the Active Console goes through one Gateway that does not enforce comments, to reach another Gateway that does, the Active Console passes the command to the Gateway. If there is no comment, Gateway returns an error. Mandatory: No Default: False ##### commands > encodedPassword Allows you to set a password for user-defined Gateway commands with [Enable Password](#commands--command--usercommand--enablepassword) set to `true`. The password is encoded using the UNIX crypt command-line utility. Mandatory: No Default: Password is not set #### Command configuration - Basic tab ##### commands > command The command section contains the definition for a single command. Each section must be uniquely named among all other commands, and additionally the command name can form part of the menu structure as seen in Active Console or be overridden by the label flag. ##### commands > command > name Specifies the name of the command. This name must be unique within the setup file. Mandatory: Yes ##### commands > command > targets A list of data-items this command will be displayed for. Targets in the list are combined using the Boolean OR operation. i.e. if any items in the list match, the command will be displayed. If the gateway has an imported data section configured then there are some restrictions to the paths that can be used. Please see [Commands](#gateway-sharing-commands). Mandatory: No Default: Command will not be displayed (can be accessed from a task or action only) ##### commands > command > targets > target An XPath name which describes the data-items that this command applies to. See [XPaths - User Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html) 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 Contains the configuration for a user command. Mutually exclusive with `task` below. Mandatory: No Default: A task is configured. ##### commands > command > task Contains the configuration for a task command. Mutually exclusive with `userCommand` above. Mandatory: No Default: A user command is configured. #### Command configuration - Advanced tab ##### commands > command > label The label is displayed to the user as the entry for this command, in the right-click menu. This should be kept relatively short so that the text can be displayed in a menu, but still describe what the command does to users. Mandatory: No Default: Command name is displayed to the user ##### commands > command > description Optional short description of the command to explain to what the command is intended for. Mandatory: No Default: No description #### User Commands User commands are the simplest form of user defined command. These commands allow users to configure programs to be run by the gateway in response to commands issued from Active Console. There are two types of user commands; script commands which run a script or executable file, and shared-library commands which run a function inside a shared library. Script commands require at least one argument which specifies the script or executable to run. Shared library commands require two arguments, the first specifying the shared library and the second the function within the shared library to run. When a command is executed, it is passed a target data-item to execute upon. This data-item will have been previously matched against the target data-items specified in the command (in order to display the menu to the ActiveConsole 2 user). This data-item is used by internal commands to act upon, and can also be referenced by user commands using the `xpath` argument type as described in [Command arguments](#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](#configuration-2). The settings for this section are as follows. An example configuration is shown below: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-user-commands.png) ##### Character limit 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 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html) for more information on XPaths. User-input arguments are the most common type of argument as they provide the most flexibility in a command. When a user attempts to execute a command containing user-input arguments, a dialog will appear on the client (e.g. ActiveConsole 2) prompting the user to fill in values for these arguments. This prompt will also describe the argument requested and additionally contain default values which the user can choose to override. #### Configuration ##### commands > command > userCommand > type The type of the user command. Valid values are `script` or `sharedLibrary`. Mandatory: Yes ##### commands > command > userCommand > runLocation The run location describes where the command will be run. Valid values are `gateway`, `netprobe` or `client`. Gateway commands will be run by gateway, while netprobe commands will be run by the Netprobe on which the context variable resides. Netprobe commands can only be specified for a script-type action, due to current limitations in Netprobe. Client commands will execute on the connected client application (ActiveConsole2). Mandatory: Yes Example script: ```xml /geneos/gateway[(@name="MNL_PUGO_GATEWAY_9370")]/directory/probe[(@name="LORO_6370")]/managedEntity[(@name="LORO")] script netprobe powershell.exe -executionpolicy bypass -file "D:\_tickets\Scripts\hello world.ps1" true ``` Once the script has been setup, you can execute the **Run PowerShell Script** command in the Active Console. ##### commands > command > userCommand > args Command arguments are configured inside the `args` section of a command, with one `arg` definition per argument. The contents of an `arg` definition are described below: Mandatory: A minimum of one argument is required ##### commands > command > userCommand > args > arg > concatenate Optional Boolean setting which controls whether the value of this argument should be concatenated to the previous argument, before being passed to the underlying script or shared‑library. This can be used to build up strings which include variables, similar to using a UNIX shell. E.g. `prefix_$(var)_postfix`, which would be done using three different `arg` nodes. Mandatory: No Defaults: False ##### commands > command > userCommand > args > arg > static A static (fixed) command argument to pass directly to the command. Mutually exclusive to text, xpath or userinput. Mandatory: No ##### commands > command > userCommand > args > arg > text A variable command argument to pass directly to the command. This can include static text or Geneos variables which will be evaluated to their respective values depending upon the target data-item the command is being executed on. Example: if a Geneos variable "`OS`" is defined with different values at 2 different Managed Entities, and the command is run on both these Managed Entities data-items, then both command instances will get different value of "`OS`" depending upon the Managed Entity data-item it is being run on. The argument type is singleLineStringVar and can consist of static data and/or any number of Geneos variables interleaved together with/without static data. E.g. "`Host:$(OS)-$(VERSION)`" where "`OS`" and "`VERSION`" are 2 pre-defined Geneos variables. Currently only the following variables values can be properly converted to string: 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 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html) 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 This defines an argument that must be provided by the user when executing a command. This is mutually exclusive to static or XPath. The argument restricts user input to that type must be one of the following types: - boolean - float - integer - singleLineString - multiLineString - options - timeInSeconds - xpathOptions - password ##### commands > command > userCommand > args > arg > userinput > description A description of the argument. This text is displayed as part of the prompt to the user for the argument value so should describe what the argument means. Mandatory: Yes ##### commands > command > userCommand > args > arg > userinput > boolean Specifies a Boolean argument, and the default argument value. Valid values are `true` or `false`. ##### commands > command > userCommand > args > arg > userinput > float Specifies a real number (i.e. with numbers after the decimal point), and the default argument value. ##### commands > command > userCommand > args > arg > userinput > integer Specifies an integer (whole number) argument, and the default argument value. ##### commands > command > userCommand > args > arg > userinput > singleLineString Specifies a text string, and the default argument value. Cannot contain newline characters. ##### commands > command > userCommand > args > arg > userinput > multiLineString Specifies a text string and default argument value. Can contain new line characters. ##### commands > command > userCommand > args > arg > userinput > timeInSeconds Specifies a time as number of seconds since 01-Jan-1970 00:00:00 UTC (i.e. a Unix timestamp). Valid values are positive integers (including 0), times cannot be negative. This is the time shown to the user when the command is run. The default value is `01-Jan-1970 00:00:00`. If the field is left as the default value, the user is shown the **current time** when the command is run. This option is recommended. Alternatively, you can use the drop-down option to specify a time. The drop-down option shows a calendar and three buttons: - Now — changes the field to the current time. - None — empties the field. This resets the time to default. - OK — the field changes to the time specified in the calendar. ##### commands > command > userCommand > args > arg > userinput > xPathOptions Takes one or more XPaths as configuration. These XPaths are evaluated on the client and the result of this is presented to you as a multiple choice selection. The XPath results are presented to you in the same order as the XPath configuration, i.e. the results of the first XPath followed by the second XPath etc. Duplicate entries are removed from the result list. ##### commands > command > userCommand > args > arg > userinput > password Prompts the user to enter the password needed to run the target script or library. The password is AES256-encrypted before it is passed to the target script or library. You must provide your own key-file when starting the Gateway. The key-file is used to encrypt the password, and therefore it is not possible to decrypt it outside the Gateway if it is encrypted using the Gateway's own key. See [Secure Passwords](https://docs.itrsgroup.com/docs/geneos/7.11.0/security/access-controls/gateway_secure_passwords/index.html). ##### commands > command > userCommand > args > arg > userinput > options Specifies a list of options the user can choose from. There must be at least one option specified. The first option in the options list is the "default option" which is displayed to the user. ##### commands > command > userCommand > args > arg > userinput > options > option A user option. ##### commands > command > userCommand > args > arg > userinput > options > option > label Optional label which is displayed to the user in place of the value. ##### commands > command > userCommand > args > arg > userinput > options > value The value which will be passed as the argument if the user selects this option. Defined as a singleLineString. ##### commands > command > userCommand > args > arg > userinput > requireArgument Specifies that the user input argument requires a value to be entered to execute the command. **Note** This is enforced by v4.10.0 Active Consoles and later. Older Active Consoles pass the command to the Gateway, which rejects the command if there is no text provided by the user for the argument. Default: `False` ##### commands > command > userCommand > environmentVariables Provides another way to share information with a script or library command. For scripts environment variables appear in the standard environment. For library commands environment variables are passed as additional arguments in name=value format. Environment variables are available for Gateway and Netprobe targets. ##### commands > command > userCommand > environmentVariables > name A name for the environment variable with the usual restrictions for identifiers. Mandatory: Yes ##### commands > command > userCommand > environmentVariables > value Value for the environment variable. May include Geneos variable references which are resolved when the command is executed. The value of an 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 Provides a way to send secured information with a script or library command. For scripts secure environment variables appear in the standard environment but remain encrypted. For library commands secure environment variables also remain encrypted and are passed as additional arguments in name=value format. Secure environment variables are available for Gateway and Netprobe targets. ##### commands > command > userCommand > secureEnvironmentVariables > name A name for the environment variable with the usual restrictions for identifiers. Mandatory: Yes ##### commands > command > userCommand > secureEnvironmentVariables > value Value for the environment variable. - `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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/gateway_operating_environment/index.html). References to invalid variables are ignored. See [Decode encrypted environment variables](https://docs.itrsgroup.com/docs/geneos/7.11.0/security/access-controls/gateway_secure_passwords/index.html#decode-encrypted-environment-variables) for details on how to decrypt these. ##### commands > command > userCommand > enablePassword This option has a different effect depending on the [Run location](#commands--command--usercommand--runlocation): - `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 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 Task commands allow a sequence of commands to be run against a target data-item as a single command run. For example, this could be used copy an executable onto a system, change its permissions, and then run it. Task commands are defined in terms of other commands in the Commands section. These can be either user commands or other task commands. You cannot create a cycle of task commands (e.g. task command A runs task command B which runs task command A again) because this would result in an infinite loop when executing any commands in the cycle. This produces an error in the GSE. **Note**  Task commands that contain commands with the **Run location** `Client` do not execute. ##### Supplying arguments for Task Commands A task can supply some or all of the arguments for its constituent commands. If you supply all of the arguments, the command can be triggered from the Active console, REST interface, or scheduled command without further prompting. If you do not supply every argument, the Active Console prompts you for the missing arguments before running them. REST and Scheduled invocations fail due to the command not having the correct number of arguments. Task arguments can either target specific arguments of a commands within the task or concatenate to the previous argument. You can therefore define complex arguments that are shared between commands. For example: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-combined-tasks.png) 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: ``` /opt/app/dest//home/ / /opt/app/dest//home/ / ``` 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: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-combined-task-archive.png) Running this on the Active Console would prompt for "Archive name" and "What to archive". If you schedule this task or run from the REST, you need to know which task arguments to target. In this case you would be targeting arguments 3 and 7.
# argument
1 <step 1 script>
2 /opt/app/dest/
3 user input argument 1
4 /home/
5 <xpath>
6 /
7 user input argument 2
8 <step 2 script>
There may be more complicated scenarios where you need to work out how to target the arguments for a task: - Take each command in turn in the order specified by the task. - Take each argument from the command numbering from 1. - If the argument is a user input check for a target argument replacement. Add this command to your list if you haven't added it before. - If a targeted argument is followed by concatenate arguments add those and continue numbering if you haven't added them already. At the end of this you will have a list of arguments that are unique from the task but may have some duplication from arguments taken directly from commands. Any user input arguments left in your list are the arguments you must target and their argument number for the task. **Note** Netprobe commands are generally not published at the time the setup is validated and applied (the applied setup then having to be applied to the connected probes). Probe commands are validated and arguments substituted when the task is executed. This may result in error messages in the Gateway and execution logs if the arguments are mis-configured. #### Configuration ##### commands > command > task This section contains the configuration for a task command. Mandatory: Yes ##### commands > command > task > commands List of the commands making up this task command. These can be any other user or task command, provided a cycle of commands if not formed. Mandatory: Yes ##### commands > command > task > commands > commandRef Reference to a command to run in the system. This can be either a user defined command or an internalCommand. Mandatory: Yes, at least one is required ##### commands > command > task > commands > commandRef > command Named reference to another user defined command in the system. This can be either a user command or a task. **Note** Cyclical task dependencies (e.g. task A calls task B which calls task A) are not allowed. This setting cannot be set if using internalCommand. ##### commands > command > task > commands > commandRef > internalCommand Reference to a command defined internally by the system. The full set of commands available is documented in [Internal Commands](#appendix-internal-commands). This setting cannot be set if using command. ##### commands > command > task > commands > commandRef > internalCommand > name Name of a command defined internally by the system. The full set of commands available is documented in [Internal Commands.](#appendix-internal-commands) Mandatory: Yes ##### commands > command > task > commands > commandRef > stopOnError Set to stop execution of the task command if this child command fails to execute. User commands follow the usual UNIX convention, so a script or executable which returns an exit code greater-than zero (>0) is viewed as an execution failure. Mandatory: Yes ##### commands > command > task > args Optional list of command arguments. This list allows you to specify an argument that is passed to several commands. Child commands with user-input arguments not specified in this section will be combined into one list, and displayed as a prompt to the user. Mandatory: No ##### commands > command > task > args > arg An argument definition. This should contain the normal contents of an `arg` definition described [above](#command-arguments) in [Task Commands](#task-commands), and additionally a `targetArgs` section which describes which child command arguments this definition applies to. Mandatory: No ##### commands > command > task > args > arg > concatenate Boolean setting which controls whether the value of this argument should be concatenated to the previous argument, before being passed to the underlying task. This can be used to build up strings which include variables, similar to using a UNIX shell. E.g. `prefix_$(var)_postfix`, which would be done using three different `arg` nodes. Mandatory: Yes ##### commands > command > task > args > arg > targetArgs List of target arguments. Mandatory: Yes ##### commands > command > task > args > arg > targetArgs > targetArg A target argument definition, specifying one of the child command arguments this task command argument should override. Mandatory: Yes, 1 is required. ##### commands > command > task > args > arg > targetArgs > targetArg > commandNumber The index of the child command in the list of commands indexed from 1. Thus 1 is the first command, 2 is the second, and so on. Mandatory: Yes ##### commands > command > task > args > arg > targetArgs > targetArg > argNumber The index of the child command argument to override indexed from 1. 1 is the first argument, 2 is the second, and so on. Mandatory: Yes ##### commands > command > task > silent Set to true to make the task run silently. N no output is written to the ActiveConsole or log file for this task. Mandatory: No Default: false ##### Example task command configuration An example configuration is shown below. In the example we reference (but do not show) a command "copy" which takes a single static argument and a command "execute" which also takes a single argument. In this example a single user input is used to satisfy both arguments. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-command-task-silent.png) The main configuration panel show the two commands being referenced for task apply patch (6). The Argument is configured here (7). ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-target-args.png) Expanding the "Target Args" dialogue shows that the argument is configured against the first argument of command 1 (copy) and command 2 (execute). ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-user-input.png) Expanding the UserInput dialogue shows the configuration of the argument. A singleLineString argument with a default of 'Patch Source'. ### Changes to Commands arguments parsing behaviour in GA4.7 The behaviour for Commands changed in Geneos v4.7 to ensure consistency when commands are run on the Gateway or Netprobe and to reduce unexpected behaviour. The following principles now apply to Commands: - Each argument is passed exactly as written, including spaces, quotes, and backslashes. There are no escape characters. For example, the output from the command below produces unexpected results prior to version 4.7: ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gw-commands-argument-parsing.png) 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: ```bash /bin/ls >> tmp.txt ``` In v4.7, this command fails to execute on both the Gateway and Netprobe: If you would like your arguments to include redirects or pipes, place the arguments into a script and use the script as the executable.
Run Location Version Output
Gateway 4.6 and below Failed to run '/bin/ls >> tmp.txt' Failed to execute '/bin/ls >> tmp.txt' with arguments ''. Exit code: 127 (error executing)
Netprobe 4.6 and below Command executes.
Gateway 4.7 and above Failed to run '/bin/ls >> tmp.txt' Failed to execute '/bin/ls >> tmp.txt' with arguments ''. Exit code: 127 (error executing)
Netprobe 4.7 and above Failed to run executable '/bin/ls >> tmp.txt' with arguments '' ()
If you would like your arguments to include redirects or pipes, place the arguments into a script and use the script as the executable. - 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** 1. If you would like to have the new behaviour on the Netprobe, then you must upgrade both Gateway and Netprobe to at least v4.7. 2. If you would like to have the new behaviour on the Gateway, then you need to upgrade the Gateway to at least v4.7. 3. Updating to v4.7 does not alter the behaviour on Windows Netprobes. ## Scheduled Commands Gateway allows the scheduling of any command in the system, including both internally-defined gateway commands and user-defined commands. These commands can be scheduled to run automatically at recurring intervals, or one-off events at a specified time. Scheduled commands run against a list of targets, which are specified using an XPath (see [XPaths - User Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html) for more information on XPaths). This allows a command to be configured against every Netprobe in the system, for example. Scheduled commands allow many different schedule types, including at exact specified times, at regular times, or more fuzzy dates such as "the second Friday of each month". Once configured, a scheduled command will execute automatically at the specified time without any further user interaction. The user must therefore provide all required command argument at configuration time, since they cannot be prompted for input when the command is run. Each run of a scheduled command will produce a log file, containing an execution log as well as any standard output and error streams from the command. The execution information of a particular scheduled command (including the success or failure of this command) is stored in a command history. A configurable number of histories are stored per command, and will persist across restarts of the gateway. ### Configuration All Scheduled Command configuration nodes are placed in the top level node scheduledCommands. #### scheduledCommands > logDirectory The directory to which Scheduled Command log files will be written. If not specified this will default to "." i.e. the working directory of the gateway. #### scheduledCommands > historyCount The number of histories per command that will be persisted. If not supplied this will default to 5. #### scheduledCommands > scheduledCommand Configuration of a single Scheduled Command. This has a mandatory **name** attribute which must be unique for each Scheduled Command per configuration. #### scheduledCommands > scheduledCommand > name Specifies the name of the scheduled command. This name must be unique within the setup file. #### scheduledCommands > scheduledCommand > command Defines the actual command that will be run as scheduled. #### scheduledCommands > scheduledCommand > command > commandRef A named reference to user-defined command that will be run as scheduled. #### scheduledCommands > scheduledCommand > command > internalCommand Allows the selection of an internal command that will be run as scheduled. #### scheduledCommands > scheduledCommand > recurrence The recurrence node controls the Scheduling part of a Scheduled Command, i.e. what time the command is run and how often it is repeated. #### scheduledCommands > scheduledCommand > args An optional list of command arguments. This list allows users to specify an argument which will override an argument in the target command. As there is no user interaction at run-time for Scheduled Commands, all user arguments must be overridden for configuration to be valid. #### scheduledCommands > scheduledCommand > args > arg An argument definition. This should contain the normal contents of an `arg` node described [above](#command-arguments) but excluding userInput option, and additionally a `targetArgs` tag which describes arguments are being overridden. #### scheduledCommands > scheduledCommand > args > arg > stdAES A secure password type for commands that take password arguments. #### scheduledCommands > scheduledCommand > args > arg > targetArgs Describes the set of arguments that are being overridden. #### scheduledCommands > scheduledCommand > args > arg > targetArgs > targetArg Defines the index of a single argument that is being overridden. #### scheduledCommands > scheduledCommand > commandPassword Defines a password argument to be used with the scheduled command which must match the password set for the probe on which the command is run. This is useful for running scheduled commands against the netprobe. The [enablePassword](#commands--command--usercommand--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](https://docs.itrsgroup.com/docs/geneos/7.11.0/security/access-controls/gateway_secure_passwords/index.html). Mandatory: No Default: Not set #### scheduledCommands > scheduledCommand > targets A set of XPaths that define a set of data-items that this scheduled command will run against. The command will run against each unique DataItem that matches these XPaths, with the unique XPath as its target. See [XPaths - User Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html) for more information on XPaths. #### Basic Configuration Example The example below shows an example configuration for a scheduled command. 1. Select the Scheduled commands top-level section. If this section does not exist, double-click to create it. 2. Select the New Scheduled Command button to create a new scheduled command. 3. Set a name for your scheduled command, link it to the command it needs to run and also, specify the target of the command. 4. Ensure the Advanced tab is visible and select the "Add new" option. This brings up a dialog. 5. Specify suitable values for the target arguments, clicking the "Add new" button for additional arguments. #### Recurrence Configuration Example As configuration of the recurrence node is complicated, it is given its own section. The recurrence node controls the Scheduling part of a Scheduled Command, i.e. what time the command is run and how often it is repeated. ##### scheduledCommands > scheduledCommand > recurrence > pattern Describes the recurrence pattern for the command. Must be one of (minutes, hours, days, weeks, months): ##### scheduledCommands > scheduledCommand > recurrence > pattern > minutes Recurs on a minutes basis. ##### scheduledCommands > scheduledCommand > recurrence > pattern > minutes > everyXMinutes The number of minutes to recur after. ##### scheduledCommands > scheduledCommand > recurrence > pattern > minutes > activeTime A name reference to a valid ActiveTime, which specifies valid times for the Scheduled Command to run. ##### scheduledCommands > scheduledCommand > recurrence > pattern > hours Recurs on an hourly basis. ##### scheduledCommands > scheduledCommand > recurrence > pattern > hours > everyXHours The number of hours to recur after. ##### scheduledCommands > scheduledCommand > recurrence > pattern > hours > activeTime A name reference to a valid ActiveTime, which specifies valid times for the Scheduled Command to run. ##### scheduledCommands > scheduledCommand > recurrence > pattern > days Recurs on a daily basis. ##### scheduledCommands > scheduledCommand > recurrence > pattern > days > everyXDays The number of days after which to recur. ##### scheduledCommands > scheduledCommand > recurrence > pattern > days > everyWeekDay Recur every weekday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks Recurs on a weekly basis. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > days The days that the command should recur. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > everyXWeeks The number of days after which to recur. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > monday Recur on a Monday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > tuesday Recur on a Tuesday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > wednesday Recur on a Wednesday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > thursday Recur on a Thursday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > friday Recur on a Friday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > saturday Recur on a Saturday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > weeks > Sunday Recur on a Sunday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months Recurs on a monthly basis. There is a choice of one of dayXOfMonth or dayOfMonth: ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > everyXMonths The number of months after which to recur. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayXofMonth The numbered day of the month on which to recur. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth Provides more control over monthly scheduling. There is a choice of one of (first, second, third, fourth, last) and (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday) of the month: ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > first First occurrence in the month. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > second Second occurrence in the month. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > third Third occurrence in the month. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > fourth Fourth occurrence in the month. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > last Last occurrence in the month. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > Monday Recur on a Monday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > tuesday Recur on a Tuesday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > wednesday Recur on a Wednesday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > thursday Recur on a Thursday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > friday Recur on a Friday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > saturday Recur on a Saturday. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > weekday Recur on a week day. ##### scheduledCommands > scheduledCommand > recurrence > pattern > months > dayofMonth > weekendday Recur on a week-end day. ##### scheduledCommands > scheduledCommand > recurrence > range Describes when the Scheduling starts and how many times it will recur. There is a choice of noEndDate, endAfterXOccurances and endBy. ##### scheduledCommands > scheduledCommand > recurrence > range > timezone Describes what timezone the start and end date (if any) should be interpreted in. This is useful when a Scheduled Command needs to be run in a timezone that is different to the local timezone that the Gateway is running in. The timezone region can be selected from the list. Mandatory: No Default: Runs in local timezone ##### scheduledCommands > scheduledCommand > recurrence > range > start The Date and Time of the first occurrence. This is in the standard xs:DateTime format. ##### scheduledCommands > scheduledCommand > recurrence > range > noEndDate No end date so continue recurring indefinitely. ##### scheduledCommands > scheduledCommand > recurrence > range > endAfterXOccurances Absolute number of runs. ##### scheduledCommands > scheduledCommand > recurrence > range > endBy The Date and Time after which no more runs will occur. This is in the standard xs:DateTime format. ## REST Service Aside from running commands via Geneos clients such as Active Console and Web Dashboard, the Gateway can enable a REST service that allows any third-party application to send requests to the Gateway to run commands, to list available commands and command targets, or to get a validation report for the Gateway setup. Applications use the REST service by sending POST requests to a Gateway REST service URL. To enable the REST service on a Gateway: 1. In the GSE, click **Commands**. 2. Select the **Advanced** tab. 3. In **Rest service**, tick the box next to **Enabled**. The Gateway REST service supports the following URLs: - `://:/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](#run-commands). - `://:/rest/runCommandOnMultipleTargets` to run a command on multiple targets. The command to run, the targets to run it against, and any required arguments are provided in a JSON data package. See [Run commands on multiple targets](#run-commands-on-multiple-targets). - `://:/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](#list-commands). - `://:/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](#list-all-commands). - `://:/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](#validate-the-gateway-setup). - `://:/rest/gatewayinfo/timezone` to obtain the Gateway time zone and the offset from UTC. See [Obtain the Gateway time zone and offset](#obtain-the-gateway-time-zone-and-offset). - `://:/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](#authorise-sso-user). - `://:/liveness` to check the liveness of the component. If the component is alive, this will return a `200` code. Otherwise, it will return a `503` code and will restart the container running the component. - `://:/rest/snapshot/dataview` to fetch a specified dataview's values, severity status, and snooze status. See [Fetch dataviews](#fetch-a-dataview). 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 the `https` protocol is used. Otherwise, the `http` protocol is used. ### REST Response The response that is sent back from the gateway depends on the type of response requested by the REST client. The REST client can specify the format it wishes the service to use for its response. The REST service supports 2 formats: - application/json - text/event-stream If the REST client requests the service use *application/json* to return its data then a JSON Response document will be returned. If the REST client requests the service use *text/event-stream* to return its data then a command output stream will be returned using the Server-sent events protocol. Currently if there is no match available for any of the requested document types, the REST Service will send a JSON Response document. #### JSON Response document The JSON response document contains some/all of the following fields: - **mimetype** [Optional] - Specifies the mimetype of the data streams that have been sent as part of the response. Currently the Gateway supports 2 mimetypes: ("text/plain", "text/html"). The mimetypes for the streams are dependant on the command that has been run. This is an array as different streams can have different mimetypes. - **status** [Required] - The status of the command. This is either "finished" or "error" - **streamdata** [Optional] - An array of data sent to different ouput streams. The streams currently supported are: + *stdout* - Output stream, where normal output from a command is placed + *stderr* - Error stream, where error output form a command is placed + *execLog* - Information about what external command the gateway/netprobe executed is placed in this stream The data from the streams can be inter-mingled. Each entry in the "streamdata" array is a JSON item with a field name that matched one of the stream names and a value that contains the data sent to that stream. The items are ordered in the array in chronological order. The JSON response document is composed once the command has finished. For Streaming commands, or long running commands where the output needs to be examined before the command has finished, this return type should not be used. Once the message has been sent, the gateway will close the connection to the REST client. If an error occurs when running the command then the appropriate HTTP status error will be returned. The error codes that the REST service can return are detailed in section [HTTP Status codes](#http-status-codes). #### Command output stream The gateway sends command output streams using [Server-sent events](https://www.w3.org/TR/eventsource/). This information is sent by the gateway as single line events. Each line starts with "data:" and ends with two end-of line markers (\r\n). Between is the command output data, which is always a JSON document. The gateway does not send out event ids or event types. The structure of the data is similar to the [JSON Response document](#json-response-document): 1. When the gateway starts the stream, it sends a mimetype message. This always contains the mime types of all 3 data streams (*stdout*, *stderr*, *execLog*). 2. This is followed by a set of command output events. Each event is a JSON document with a field name that matches one of the stream names and a value that contains the data sent to that stream. 3. Finally, the gateway sends a status message with a value of "finished" or "error". **Note** The gateway does not close the connection. It is the responsibility of the REST client to close the connection when it has seen the status message. Gateway currently does not support reconnecting to command output streams. If the connection is dropped, then the gateway will cancel the command if has not already finished. A client that attempts to reconnect will rerun the command. Below is an example of a curl command that gets data via the command output stream. **Curl Command** ```bash 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** ```json # 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](#http-status-codes). When the command output stream starts, the HTTP status is sent. A status of 200 OK is sent if no error is detected at this point. ### Run commands To run a command, the application sends a POST request to the `runCommand` URL with a JSON data package which should contain some/all of the following things - **command** [Required] : Name of the command that the REST client requires the gateway to run - **target** [Required] : XPath name that identifies the location in the gateway directory where the command should be run. The xpath need not be the full unique name of an item, but must unambiguously identify a single 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html#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](#appendix-internal-commands). The arguments for user defined commands are the arguments list defined in [Command arguments](#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](#rest-response). This section contains a number of examples of using curl to run commands using the REST API. In all these examples the following assumptions are made: - Curl is run on the gateway machine - The REST service is configured to service both secure and insecure connections - The gateway is listening insecurely on port 7039 - Gateway name is GW - Probe name is P - Managed Entity name is ME - There is a user command cmd1 that prints "Hello World" #### Command with no arguments This example runs a command with no arguments and gets back the command's response. The command in this example will show the snooze information for Managed Entity ME. In order for this command to return without an error, the Managed Entity ME must be snoozed. **Curl Command** ```bash 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** ```json { "mimetype": [ { "stdout": "text/plain" } ], "streamdata": [ { "stdout": "Data Item : /geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]\n" }, { "stdout": "Snoozed by : ActiveConsole1\n" }, { "stdout": "Snoozed by Fullname : ActiveConsole1\n" }, { "stdout": "Snoozed on : Wed 11 May 2016 10:59:46\n" }, { "stdout": "Comment : Under Maintenance\n" }, { "stdout": "Snooze type : Until specified time\n" }, { "stdout": "Unsnoozed : Wed 11 May 2016 21:59:46\n" } ], "status": "finished" } ``` #### Command with no output An example of a command that returns no data is the Gateway reload command. This is called with a target of the gateway directory and again has no arguments set. **Curl Command** ```bash curl -X POST -s --data \ '{ "command": "/GATEWAY:reloadSetup", "target": "/geneos/gateway[(@name=\"GW\")]/directory" }' \ http://localhost:7039/rest/runCommand ``` **Gateway Response** ```json { "status": "finished" } ``` #### Command with Arguments Examples of a commands that needs arguments are the snooze commands. We can use the */SNOOZE:severityTo* to snooze a ManagedEntity until its severity changes to a specified value. This command takes 4 arguments; - User Comment : This is a text field that the user sets to remind themselves of why the snooze was applied. - Severity : This is an Xpath argument that is normally filled by the Geneos client. In this case it is expected to contain the value of the current severity. The REST client does not need to set this value as the gateway will look up the value from using the xpath and the target. However the REST client can pass a value that will override this value. (It may do this if it wishes to indicate the severity it was working with at the time the command was run). - Static value "severityTo". This should never be set by the REST client. The REST Service does not allow static values to be changed. - Target Severity : This is the Severity the Gateway will watch for. When the target changes to this severity the gateway will unsnooze the command target. This value is a severity and so should be an integer between 0 and 3. For our example we will Snooze Managed Entity ME until the severity goes to 'OK' (value 1). We know that currently the severity of the Managed Entity is 'Critical' (value 3) so will inform the gateway of this fact. **Curl Command** ```bash 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** ```json { "status": "finished" } ``` #### User defined Command A final example is running a User defined command. This command runs the script '/bin/echo "Hello World"', as can be seen from the data returned in the execLog stream. **Curl Command** ```bash 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** ```json { "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" } ``` ### Run commands on multiple targets **Note** This endpoint is only available for `/SNOOZE` commands. To run a command on multiple targets, the third-party application must send a POST request to the `runCommandOnMultipleTargets` URL with a JSON data package. The request should contain the following: | Parameter | Description | |-------|-------| | command | Name of the command that the REST client requires the Gateway to run. Mandatory: Yes | | targets | An array of XPath names that identify the locations in the Gateway directory where the command should be run. Each command has restrictions on which targets it can be run on. See [Internal commands](#appendix-internal-commands) for more information. Mandatory: Yes | | args | Arguments required by the command. Each command has a number of arguments. - The arguments for internal commands are defined in [Internal commands](#appendix-internal-commands). - The arguments for user-defined commands are defined in [Command arguments](#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. Mandatory: No | | limit | The maximum number of targets to run the command on. If not specified, the default is 100. Mandatory: No | The format of the REST service response can be controlled using HTTP content negotiation for each target. See [REST Response](#rest-response). Below are examples of using cURL to run commands on multiple targets using the REST API. In all these examples, the following assumptions are made: - The cURL command 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. - The Gateway name is `Gateway`. - The probe name is `P`. - The Managed Entity names are `ME_A` and `ME_B`. #### Run a command with no arguments This example runs a snooze command on an absolute path that applies to multiple targets and receives the command's response. The sample command will snooze Managed Entity ME_A and Managed Entity ME_B until the snooze is manually removed. For each applicable target, the command will return a response containing the snooze information. It will also provide a status indicating whether the command has finished running on all targets. **cURL command** ```bash curl -X POST -s --data '{ "command" : "/SNOOZE:info", "targets" : ["/geneos/gateway/directory/probe/managedEntity"]}' http://localhost:7039/rest/runCommandOnMultipleTargets ``` **Gateway response** ```json { "results": [ { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_A\")]", "mimetype": [ { "stdout": "text/plain" } ], "streamdata": [ { "stdout": "Executed on Gateway \"Gateway\".\n" }, { "stdout": "Data Item : /geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_A\")]\n" }, { "stdout": "Snoozed by : ActiveConsole1\n" }, { "stdout": "Snoozed by Fullname : ActiveConsole1\n" }, { "stdout": "Snoozed on : Wed 02 Jul 2025 15:57:01\n" }, { "stdout": "Comment : Snoozed ME_A\n" }, { "stdout": "Snooze type : Manual\n" }, { "stdout": "Unsnoozed : When manually unsnoozed\n" } ], "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_B\")]", "mimetype": [ { "stdout": "text/plain" } ], "streamdata": [ { "stdout": "Executed on Gateway \"Gateway\".\n" }, { "stdout": "Data Item : /geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_B\")]\n" }, { "stdout": "Snoozed by : ActiveConsole1\n" }, { "stdout": "Snoozed by Fullname : ActiveConsole1\n" }, { "stdout": "Snoozed on : Wed 02 Jul 2025 15:57:19\n" }, { "stdout": "Comment : Snoozed ME_B\n" }, { "stdout": "Snooze type : Manual\n" }, { "stdout": "Unsnoozed : When manually unsnoozed\n" } ], "status": "finished" } ], "status": "finished" } ``` #### Run a command with no output This example runs a snooze command on an absolute path that applies to multiple targets and returns no data other than the target and status of the command on each target. This sample command will snooze all the dataviews of Managed Entity ME until the snooze is manually removed. **cURL command** ```bash curl -X POST -s --data '{ "command" : "/SNOOZE:manualAllMe", "targets" : ["/geneos/gateway/directory/probe/managedEntity/sampler/dataview"], "limit": 100 }' http://localhost:7039/rest/runCommandOnMultipleTargets ``` **Gateway response** ```json { "results": [ { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"CPU\")][(@type=\"\")]/dataview[(@name=\"CPU\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"DEVICEIO-Linux\")][(@type=\"\")]/dataview[(@name=\"DEVICEIO-LINUX\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"FKM\")][(@type=\"\")]/dataview[(@name=\"FKM\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"GwClientConnection\")][(@type=\"\")]/dataview[(@name=\"GwClientConnection\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"HW\")][(@type=\"\")]/dataview[(@name=\"HW\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"No_Schema_toolkit\")][(@type=\"\")]/dataview[(@name=\"No_Schema_toolkit\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"Toolkit_shell\")][(@type=\"\")]/dataview[(@name=\"Toolkit_shell\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"disk\")][(@type=\"\")]/dataview[(@name=\"disk\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"hardware\")][(@type=\"\")]/dataview[(@name=\"hardware\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"network\")][(@type=\"\")]/dataview[(@name=\"network\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"processes\")][(@type=\"\")]/dataview[(@name=\"processes\")]", "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME\")]/sampler[(@name=\"scheduledCommandData\")][(@type=\"\")]/dataview[(@name=\"scheduledCommandData\")]", "status": "finished" } ], "status": "finished" } ``` #### Run a command that returns an error The following example shows how the REST service responds when running a non-existing multi-target command. The command `/SNOOZE:UnknownCommand` is not a valid command, so the Gateway returns an error in response. **cURL command** ```bash curl -X POST -s --data '{ "command" : "/SNOOZE:UnknownCommand", "targets" : ["/geneos/gateway/directory/probe/managedEntity/sampler/dataview"] }' http://localhost:7039/rest/runCommandOnMultipleTargets | jq ``` **Gateway response** ```json { "mimetype": [ { "stderr": "text/plain" } ], "streamdata": [ { "stderr": "Cannot find Command: '/SNOOZE:UnknownCommand'" } ], "status": "error" } ``` #### Run a command with mixed absolute and relative target paths The following example shows how the REST service responds when running a multi-target command on a combination of absolute and relative target paths. The response shows different outputs for each target and their statuses. **cURL command** ```bash curl -X POST -s --data '{ "command" : "/SNOOZE:info", "targets" : ["/geneos/gateway/directory/probe/managedEntity", "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_B\")]/sampler[(@name=\"Toolkit\")][(@type=\"\")]/dataview[(@name=\"Toolkit\")]/rows/row[(@name=\"SqlConnection\")]/cell[(@column=\"status\")]" ]}' http://localhost:7039/rest/runCommandOnMultipleTargets ``` **Gateway response** ```json { "results": [ { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_A\")]", "mimetype": [ { "stdout": "text/plain" } ], "streamdata": [ { "stdout": "Executed on Gateway \"Gateway\".\n" }, { "stdout": "Data Item : /geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_A\")]\n" }, { "stdout": "Snoozed by : ActiveConsole1\n" }, { "stdout": "Snoozed by Fullname : ActiveConsole1\n" }, { "stdout": "Snoozed on : Wed 02 Jul 2025 15:57:01\n" }, { "stdout": "Comment : Snoozed ME_A\n" }, { "stdout": "Snooze type : Manual\n" }, { "stdout": "Unsnoozed : When manually unsnoozed\n" } ], "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_B\")]", "mimetype": [ { "stdout": "text/plain" } ], "streamdata": [ { "stdout": "Executed on Gateway \"Gateway\".\n" }, { "stdout": "Data Item : /geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_B\")]\n" }, { "stdout": "Snoozed by : ActiveConsole1\n" }, { "stdout": "Snoozed by Fullname : ActiveConsole1\n" }, { "stdout": "Snoozed on : Wed 02 Jul 2025 15:57:19\n" }, { "stdout": "Comment : Snoozed ME_B\n" }, { "stdout": "Snooze type : Manual\n" }, { "stdout": "Unsnoozed : When manually unsnoozed\n" } ], "status": "finished" }, { "target": "/geneos/gateway[(@name=\"Gateway\")]/directory/probe[(@name=\"P\")]/managedEntity[(@name=\"ME_B\")]/sampler[(@name=\"Toolkit\")][(@type=\"\")]/dataview[(@name=\"Toolkit\")]/rows/row[(@name=\"SqlConnection\")]/cell[(@column=\"status\")]", "mimetype": [ { "stderr": "text/plain" }, { "stdout": "text/plain" } ], "streamdata": [ { "stdout": "Executed on Gateway \"Gateway\".\n" }, { "stderr": "Unable to find snooze record for the selected item.\nIf this item appears snoozed, it may be because of a rule.\n" } ], "status": "finished" } ], "status": "finished" } ``` An `stderr` output does not automatically imply that the command failed. In this case, it was executed successfully, but the snooze information was not found for the specified target. ### List commands The REST service supports two requests that allow applications to determine what commands are available via the `runCommand` URL. Both requests return full details of each command, including the targets (XPath locations within the Gateway directory structure) at which it can be run and the arguments it supports. #### List all commands To list all the commands that can be executed via the REST interface, the application sends a GET or POST request to the `commands/all` URL. No additional parameters are required for this endpoint. Example usage (assuming a Gateway accepting REST requests on its insecure port and listening on port 7039): ```bash 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 **Geneos PCRE2 upgrade** Beginning with version 7.3.x, Geneos now uses `PCRE2 10.44` by default, upgrading from `PCRE 8.44` for improved handling of regular expressions. Please be aware that this may introduce breaking changes to your implementation. For more information about the differences, refer to the [PCRE2 documentation](https://www.pcre.org/current/doc/html/pcre2compat.html). 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_xpath_ug/index.html#target-names-and-relative-paths)). - **namePattern** [Optional] : Regular expression (using PCRE2 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): ```bash curl -X POST -s --data \ '{ "target": "/geneos/gateway[(@name=\"GW\")]/directory/probe[(@name=\"P\")]", "namePattern": "^/SNOOZE:[mi]" }' \ http://localhost:7039/rest/commands/available ``` If user authentication is enabled, this endpoint will list only the commands which are available to the user whose credentials are provided in the request. #### JSON command list response The response sent back from the gateway for a successful request to either the `commands/all` or the `commands/available` endpoint is a JSON object containing an array of command descriptions: ```json { "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: ```json { "error": "Command target matches more than one item" } ``` ### Find items matching a target The REST service supports two requests that allow applications to determine what data items are known to the Gateway and which can be specified as targets for a given command. Both these requests return an array of XPath names each of which uniquely identifies a data item. #### All items matching a target XPath To list all items matching a given XPath (regardless of whether any commands are available on the items), the application sends a GET or POST request to the `xpaths/match` URL with a JSON package which identifies the target and may override the default limit on the number of items returned. That is, the POST data is a JSON object with the following keys: - **target** [Required] : XPath name selecting the data items to list. This path will be evaluated against the whole directory of data items known to the Gateway. - **limit** [Optional] : Integer value to override the default limit of 100 items. By default, if the target path matches more than 100 items, the request will be rejected. Note that attempting to retrieve a very large number of XPaths will force the Gateway to allocate a very large amount of memory to service the request, which may harm its performance. Example usage, listing all managed entities (assuming that there are fewer than 100): ```bash curl -X GET -o cmdresult.json -s --data '{ "target":"//managedEntity" }' http://localhost:7039/rest/xpaths/match ``` **Note** This endpoint will not take permissions into account. If authentication is enabled, it is available to any authenticated user. #### Items which are targets for a given command To list data items which are valid targets for a given command and which match a given target XName, the application sends a GET or POST request to the `xpaths/commandTargets` URL with a JSON package which identifies the command and target and may override the default limit on the number of items considered. That is, the POST data is a JSON object with the following keys: - **target** [Required] : XPath name selecting the data items to check as targets of the command. This path will be evaluated against the whole directory of data items known to the Gateway. - **command** [Required] : Name of the command against which to check the data items matching the target XPath. - **limit** [Optional] : Integer value to override the default limit of 100 items. By default, if the path matches more than 100 items (regardless of whether they are valid targets for the command), the request will be rejected. Note that attempting to check a very large number of data items will force the Gateway to allocate a very large amount of memory to service the request, which may harm its performance. Example usage, listing all managed entities which can be unsnoozed (assuming that there are fewer than 100 managed entities in total): ```bash curl -X GET -o cmdresult.json -s --data \ '{ "target":"//managedEntity", "command":"/SNOOZE:unsnooze" }' \ http://localhost:7039/rest/xpaths/commandTargets ``` If user authentication is enabled, this endpoint will list only the items for which the requesting user can run the command. #### JSON XPath list response The response sent back from the gateway for a successful request to either the `xpaths/match` or the `xpaths/commandTargets` endpoint is a JSON object containing an array of XPaths, each of which is the unique name of a data item: ```json { "xpaths": [ "/geneos/gateway[(@name=\"devGW\")]/directory/probe[(@name=\"theProbe\")]/managedEntity[(@name=\"apps\")]", "/geneos/gateway[(@name=\"devGW\")]/directory/probe[(@name=\"theProbe\")]/managedEntity[(@name=\"basics\")]", "/geneos/gateway[(@name=\"devGW\")]/directory/probe[(@name=\"vp\")]/managedEntity[(@name=\"GatewayInfo\")]" ] } ``` The array of XPaths will be empty if no data items meet the given criteria. #### Run a command against multiple targets The output of the `xpaths/commandTargets` endpoint is a list of targets suitable for passing to the `runCommand` endpoint. To run a command against multiple targets, an application can use the `xpaths/commandTargets` endpoint to obtain a list of targets and then use the `runCommand` endpoint to run the command for each target. The Gateway distribution includes a script, `resources\rest\apply-commands.sh`, which does just this. For example, to snooze all managed entities whose "Foo" attribute is set to "Bar", the script could be run as follows: ```bash 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 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): ```bash 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 ```json { "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: ```json { "validationResult": { "maxSeverity": "Error", "issues": [ { "severity": "Error", "module": "CommandManager", "description": "Command name is missing or empty - skipping this command definition.", "xpathLocation": "/gateway[@disabled!=\"true\"][1]/commands[@disabled!=\"true\"][1]/commandGroup[@disabled!=\"true\"][1]/command[@disabled!=\"true\"][1]", "includeFile": "smartTk.setup.xml" }, { "severity": "Warn", "module": "RestService", "description": "Invalid value 'true' for maxBufferSize setting, expecting Integer value. Using default of '1024", "xpathLocation": "/gateway[@disabled!=\"true\"][1]/commands[@disabled!=\"true\"][1]/restService[@disabled!=\"true\"][1]/maxBufferSize[@disabled!=\"true\"][1]" } ] } } ``` ### Obtain the Gateway time zone and offset The remote Gateway time zone and the offset from Coordinated Universal Time (UTC) is retrieved using this REST endpoint. This enables you to issue remote REST commands with `date` and `time` parameters without having to first calculate the time difference. The `timezone` name in the response is the first existing value from the following: 1. The time zone specified in the [operatingEnvironment > timezone](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/gateway_operating_environment/index.html#operatingenvironment--timezone) configuration setting. 2. The value of the `TZ` environment variable. 3. (Linux only) The part after the string `"/zoneinfo/"` from the value of the `/etc/localtime` symbolic link. The `timezone` name only appears in the response if a value was obtained from one of the above. The offset from UTC is calculated from the difference between the results of calling `gmtime` and `localtime`. **Note** The endpoint does not assess permissions. If authentication is enabled, it is available to any authenticated user. #### Response ```json { "gatewayinfo": { "timezone": "Europe/London", "localTime": "2018-05-22T03:25:07", "offsetFromUtc": "+01:00" } } ``` ### Authorise SSO User **Note** This endpoint is not supported when ITRS Analytics is used as the SSO provider. To obtain an SSO token in this case, please see [Obtaining an SSO token from ITRS Analytics](#obtaining-an-sso-token-from-itrs-analytics). 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](#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 ```bash curl -L --location-trusted --negotiate --user : -X GET -s -N http://localhost:18066/rest/authorize ``` #### SSO Agent Response ```json { "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: ```bash SSO_TOKEN=$(curl -L --location-trusted --negotiate --user : -X GET -s -N http://localhost:18066/rest/authorize | jq -r '.access_token') ``` ### Fetch a dataview 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: ```json { "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 The response is a JSON document that contains something similar to: ```json { "dataview": { "timestamp": "2015-07-01T16:18:23.263Z", "snoozed": false, "snoozed-ancestors": false, "headlines": { "a": { "value": "misc", "severity": "CRITICAL", "snoozed": true, "assigned": true, "assigned-to": "Chris" }, "b": { "value": "1234514", "severity": "UNDEFINED", "snoozed": false, "assigned": false } }, "table-columns": [ "Row", "a", "b" ], "table": { "row1": { "a": { "value": "string", "severity": "UNDEFINED", "active": false, "snoozed": false, "assigned": false }, "b": { "value": "334", "severity": "UNDEFINED", "snoozed": false, "assigned": false } }, "row2": { "a": { "value": "another string", "severity": "UNDEFINED", "snoozed": false, "assigned": false }, "b": { "value": "345", "severity": "UNDEFINED", "snoozed": false, "assigned": false } } } } } ```
Field Description
target Specify an XPATH that resolves to a single dataview.
scope

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

The available options are:

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

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

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

  • user-assignment — returns the user assignment state of each cell together with the user a cell is assigned to.
### HTTP Status codes The following HTTP error codes will be returned if the REST service encounters an error: - *OK (200)*: This will be returned if the REST service runs the command successfully. - *Bad Request (400)*: This will be returned if the POST data is not well-formed JSON or if a mandatory item is missing. - *Forbidden (403)*: This will be returned if the user provides invalid credentials (and credentials are required). It will also be returned if the user's credentials are correct but the user does not have permission to run the command requested on the target requested. - *Not Found (404)*: This will be returned if the service is not available. It can occur if the gateway is not running a REST service. It can also occur if the REST service is secure but the request is made on the gateway's insecure port. - *Internal Server Error (500)*: This will be returned if the command run returns an error. ### HTTPS Connections If the gateway is setup to allow secure connections, it is possible to use the HTTPS protocol rather than the HTTP one. The REST client will need to implicitly trust the gateway's certificate if its certificate authorities have not signed it. It is possible to configure the REST service to only run on secure connections. (See [restService > allowOnInsecureComms](#commands--restservice--allowoninsecurecomms)) ### User Authentication If the gateway is configured with authentication enabled, then all REST command requests must come with user credentials that the gateway can verify. The REST service supports two types of user credentials. SSO tokens can be used to authenticate SSO users. User name and password can be used to authenticate users who have passwords configured in the gateway setup. System logins are not supported, since system credentials are checked by the user interface client (e.g. Active Console), which is not involved in the REST API. However, it is possible to use System login for Active Console users while using password-based authentication for the REST API. For password-based authentication, each REST command must be accompanied by a username and password, using HTTP basic access authentication. For example, using Curl: ```bash 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 ITRS Analytics, please see [Obtaining an SSO token from ITRS Analytics](#obtaining-an-sso-token-from-itrs-analytics). 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: ```bash 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](#permissions)) #### Obtaining an SSO token from ITRS Analytics If the SSO provider is ITRS Analytics, an SSO token can be obtained directly from the ITRS Analytics authorization endpoint, using the following curl command: ```bash 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 ITRS Analytics will be in the following format: ```json { "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: ```bash 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 #### commands > restService This section contains the configuration for the gateway REST service. If the section does not exist then the REST service is not enabled. Mandatory: No Default: REST service disabled #### commands > restService > enabled Boolean value controlling whether REST service is enabled or not. Mandatory: No Default: false #### commands > restService > allowOnInsecureComms This flag enables the REST service to work on both secure and insecure connections. Thus allowing HTTP and HTTPS connections. The HTTP requests need to be made to the gateway's insecure listen port while the HTTPS requests need to be made to the gateway's secure listen port. Mandatory: No Default: false #### commands > restService > maxBufferSize This is the maximum size of a single command buffer (in Kb). When requesting JSON response, the gateway buffers all the data until the command has complete. If the command is a streaming command, this may never happen and the buffer will grow as more and more data is received. Should the data buffer exceed this size, then the gateway will cancel the command and return the currently generated output with an error message indicating that the command buffer has been exceeded. Mandatory: No Default: 1024 Kb ## Appendix: Internal Commands ### Introduction This appendix provides information on commands available on the Gateway and from Netprobes. The specifics of commands and command targets vary depending on your Gateway setup. To get a list of commands that is accurate to your Gateway, see [REST Service](#rest-service). ### System commands System commands are commands which allow control of the system. #### Snooze commands Snooze commands allow control over the gateway snooze functionality. Most snooze commands have two forms of the command, named as follows: `/SNOOZE:`, for example `/SNOOZE:untilChanges` `/SNOOZE:AllMe`, for example `/SNOOZE:untilChangesAllMe` In these cases the short named version of the command is available for directory, probe and managedEntity data-items. The longer `AllMe` version of the command is available for sampler, dataview and cell data-items. The `AllMe` versions have an additional parameter (labelled 'Snooze on' in the GUI) which allows the command to be run on a single managedEntity or multiple managedEntities matching by sampler or plug-in. An exception to this convention is `/SNOOZE:untilValueChanges` which is valid on cell data-items only. **Note** Snoozing until severity changes may not work as expected if severity changes to 'undefined'. If the rule(s) which apply to an item ever set its severity to undefined, then the following scenario is possible: - The item is snoozed 'until severity changes' when the severity is OK, Warning or Critical. - The host gateway or the source of data (netprobe or gateway) is restarted. - The severity of the item is recalculated as 'undefined' after the restart. Because data items are created with undefined severity and the unsnoozing mechanism depends on detecting a change in severity, the item remains snoozed. If the item were to be automatically unsnoozed in this scenario, it would also be (wrongly) unsnoozed even if its severity was about to be reset to the previous value (such as Critical) by a rule. In general, ITRS recommends that the severity of a data item should not be explicitly set to undefined by a rule. **/SNOOZE:manual**
Path Snooze/Manual
Long Description Snooze until manually unsnoozed
Effect Snoozes a data-item until manually unsnoozed by a user using the /SNOOZE:unsnooze command.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static manual
4 Static 0
**/SNOOZE:manualAllMe**
Path Snooze/Manual
Long Description Snooze until manually unsnoozed with options to snooze on all managedEntities.
Effect Snoozes a data-item until manually unsnoozed by a user using the /SNOOZE:unsnooze command.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | manual | | | 4 | Static | 0 | | All ManagedEntities | 5 | User input: Options| - This managed only (this) - All ManagedEntities match on sampler (sampler) - All ManagedEntities match on plugin (plugin) | **/SNOOZE:severityTo**
Path Snooze/Severity to
Long Description Snooze until severity changes to…
Effect Snoozes a data-item until the severity of the data-item changes to the specified value.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | 2 | XPath | state/@severity | | | | 3 | Static | severityToOrTime | | Target severity | 4 | User input: Integer | 1 | **/SNOOZE:severityToAllMe**
Path Snooze/Severity to
Long Description Snooze until severity changes to… with options to snooze on all managedEntities.
Effect Snoozes a data-item until the severity of the data-item changes to the specified value.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | severityToOrTime | | Target severity | 4 | User input: Integer | 1 | | All ManagedEntities | 5 | User input: Options| - This managed only (this) - All ManagedEntities match on sampler (sampler) - All ManagedEntities match on plugin (plugin) | **/SNOOZE:untilChanges**
Path Snooze/Until changes
Long Description Snooze until severity changes
Effect Snoozes a data-item until the severity of the data-item changes from the severity when it was snoozed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | severityFrom | | | 4 | Static | 0 | **/SNOOZE:untilChangesAllMe**
Path Snooze/Until changes
Long Description Snooze until severity changes, with options to snooze on all managedEntities.
Effect Snoozes a data-item until the severity of the data-item changes from the severity when it was snoozed.
**Target** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | severityFrom | | | 4 | Static | 0 | | All ManagedEntities | 5 | User input: Options | - This managed only (this) - All ManagedEntities match on sampler (sampler) - All ManagedEntities match on plugin (plugin) | **/SNOOZE:time**
Path Snooze/Time period
Long Description Snooze for a specified time period
Effect Snoozes a data-item for the specified time period from the time at which the snooze command is executed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | time | | Duration | 4 | User input: Float | 24 | | | 5 | User input: Options | - Hours (3600) - Minutes (60) - Days (86400) | **/SNOOZE:timeAllMe**
Path Snooze/Time period
Long Description Snooze for a specified time period, with options to snooze on all managedEntities.
Effect Snoozes a data-item for the specified time period from the time at which the snooze command is executed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | time | | Duration | 4 | User input: Float | 24 | | | 5 | User input: Options | - Hours (3600) - Minutes (60) - Days (86400) | | All ManagedEntities | 6 | User input: Options | - This managed only (this) - All ManagedEntities match on sampler (sampler) - All ManagedEntities match on plugin (plugin) | **/SNOOZE:dateTime**
Path Snooze/Until Date / Time
Long Description Snooze until a specified date and time
Effect Snoozes a data-item until the specified date and time.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | dateTime | | Date | 4 | User input: String YYYY-MM-DD format. | YYYY-MM-DD defaults to today's date. | | Time | 5 | User input: String HH:MM timezoneRegion 24hr clock format time, optional timezoneRegion. | HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used. See [Snooze Until Command](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/monitoring-and-alerts/geneos_commands_tr/index.html#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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/monitoring-and-alerts/geneos_commands_tr/index.html#snooze-until-command) for more info. | | All ManagedEntities | 6 | User input: Options | - This managed only (this) - All ManagedEntities match on sampler (sampler) - All ManagedEntities match on plugin (plugin) | **/SNOOZE:severityToOrTime**
Path Snooze/Severity to
Long Description Snooze until severity changes to Critical/Warning/Undefined/Ok Or Snooze for specified time period.
Effect Snoozes a data-item until the severity of the data-item changes to the specified value or the time period expires.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | severityTo | | Target severity | 4 | User input: Integer | 1 | | | 5 | Static | time | | Duration | 6 | User input: Float | 24 | | | 7 | User input: Options | - Hours (3600) - Minutes (60) - Days (86400) | **/SNOOZE:severityToOrTimeAllMe**
Path Snooze/Severity to
Long Description Snooze until severity changes to Critical/Warning/Undefined/Ok Or Snooze for specified time period with options to snooze on all managedEntities.
Effect Snoozes a data-item until the severity of the data-item changes to the specified value or the time period expires.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler ``` **Arguments**
Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static severityTo
Target severity 4 User input: Integer 1
5 Static time
Duration 6 User input: Float 24
7 User input: Options Hours (3600), Minutes (60), Days (86400)
All ManagedEntities 8 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)
**/SNOOZE:untilValueChanges**
Path Snooze/Until Value Changes
Long Description Snooze a cell until its value changes.
Effect Snooze a cell for as long as its value remains the same as the point at which it was snoozed. This is valid for cell data-items only.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
2 XPath state/@severity
3 Static untilValueChanges
Duration 4 XPath @value
All ManagedEntities 5 User input: Options This managed only (this), All ManagedEntities match on sampler (sampler), All ManagedEntities match on plugin (plugin)
**/SNOOZE:unsnooze**
Path Snooze/Unsnooze
Long Description Unsnooze a snoozed item.
Effect Unsnoozes a snoozed item immediately, and cancels any snooze conditions upon that item (e.g. until severity changes).
**Targets** ``` /geneos/gateway/directory/probe/managedEntity[(state(\"snoozed\")=1)] /geneos/gateway/directory/probe[(state(\"snoozed\")=1)] /geneos/gateway/directory[(state(\"snoozed\")=1)] ``` **Arguments**
Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
**Note** The user comment argument is part of the command only if **Require Snooze Comments** is enabled. See [commands > requireSnoozeComments](#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](#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 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_timeformats_tr/index.html) for more information). There are 3 versions of `/SNOOZE:until` command: - `/SNOOZE:until` which applies to directory, probe and managedEntity data-items. - `/SNOOZE:untilAllMe` which applies to sampler and dataview. - `/SNOOZE:untilAllMeCell` which applies to cell data-items. `/SNOOZE:untilAllMe` and `/SNOOZE:untilAllMeCell` commands have additional parameter which allows the command to be run on a single managedEntity or multiple managedEntities matching by sampler or plug-in. **/SNOOZE:until**
Path Snooze/Until Severity/Time/ Date /Time
Long Description Snooze until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached
Effect Snoozes a data-item until severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached
**Targets** ``` /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | until | | Value | 4 | Static | Value (Unused) | | | 5 | Static | 0 (Unused) | | Severity | 6 | User input: Boolean | false | | | 7 | User input: Options | severityFrom (0), severityTo(1) | | Target severity | 8 | User input: Integer | 1 | | Time | 9 | User input: Boolean | false | | Duration | 10 | User input: Float | 24 | | | 11 | User input: Options | - Hours (3600) - Minutes (60) - Days (86400) | | Date/Time | 12 | User input: Boolean | false | | Date | 13 | User input: String YYYY-MM-DD format. | YYYY-MM-DD defaults to today's date. | | Time | 14 | User input: String HH:MM timezoneRegion 24hr clock format time, optional timezoneRegion. | HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used. | **/SNOOZE:untilAllMe**
Path Snooze/Until Severity/Time/ Date /Time
Long Description Snooze until severity changes (optionallyto Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached with options to snooze on all managedEntities
Effect Snoozes a data-item until severity changes, (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | until | | Value | 4 | Static | Value (Unused) | | | 5 | Static | 0 (Unused) | | Severity | 6 | User input: Boolean | false | | | 7 | User input: Options | severityFrom (0), severityTo(1) | | Target severity | 8 | User input: Integer | 1 | | Time | 9 | User input: Boolean | false | | Duration | 10 | User input: Float | 24 | | | 11 | User input: Options | - Hours (3600) - Minutes (60) - Days (86400) | | Date/Time | 12 | User input: Boolean | false | | Date | 13 | User input: String YYYY-MM-DD format. | YYYY-MM-DD defaults to today's date. | | Time | 14 | User input: String HH:MM timezoneRegion 24hr clock format time, optional timezoneRegion. | HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used. | | All ManagedEntities | 15 | User input: Options| - This managed only (this) - All ManagedEntities match on sampler (sampler) - All ManagedEntities match on plugin (plugin) | **/SNOOZE:untilAllMeCell**
Path Snooze/Until Value/Severity/Time/ Date /Time
Long Description Snooze a cell until value or severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached with options to snooze on all managedEntities
Effect Snoozes a cell until value or severity changes (optionally to Critical/Warning/Undefined/Ok) or time elapses or a specified date / time is not reached
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User comment | 1 | User input: MultiLineString | | | | 2 | XPath | state/@severity | | | 3 | Static | until | | Value | 4 | User input: Boolean | Value (Unused) | | | 5 | XPath | @value | | Severity | 6 | User input: Boolean | false | | | 7 | User input: Options | severityFrom (0), severityTo(1) | | Target severity | 8 | User input: Integer | 1 | | Time | 9 | User input: Boolean | false | | Duration | 10 | User input: Float | 24 | | | 11 | User input: Options | - Hours (3600) - Minutes (60) - Days (86400) | | Date/Time | 12 | User input: Boolean | false | | Date | 13 | User input: String YYYY-MM-DD format. | YYYY-MM-DD defaults to today's date. | | Time | 14 | User input: String HH:MM timezoneRegion 24hr clock format time, optional timezoneRegion. | HH:MM must be set to a valid time. If timezoneRegion is not specified, the Gateway's time zone will be used. | | All ManagedEntities | 15 | User input: Options | - This managed only (this) - All ManagedEntities match on sampler (sampler) - All ManagedEntities match on plugin (plugin) | #### User Assignment commands 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](#commands-requireuserassignmentcomments). **/USERASSIGNMENT:info**
Path User Assignment/Info
Long Description Shows user assignment information for the selected data-item.
Effect Displays information on the assigned data-item including assignment time, data-item name, assigned user, assigned by and comment.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview[(state(\"userAssigned\")=1)] /geneos/gateway/directory/probe/managedEntity/sampler[(state(\"userAssigned\")=1)] /geneos/gateway/directory/probe/managedEntity[(state(\"userAssigned\")=1)] /geneos/gateway/directory/probe[(state(\"userAssigned\")=1)] /geneos/gateway/directory[(state(\"userAssigned\")=1)] ``` **Arguments** None **/USERASSIGNMENT:assignToMe**
Path User Assignment/Assign To Me
Long Description Assign DataItem to a user
Effect Assigns the selected data-item to the user logged onto that Gateway.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
User comment 1 User input: MultiLineString
**/USERASSIGNMENT:assign**
Path User Assignment/Assign
Long Description Assign DataItem to a user
Effect Assigns the selected data-item to the user entered by the caller.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User input: MultiLineString
**/USERASSIGNMENT::assignUntilSeverityChangesTo**
Path User Assignment/Assign Until Severity Changes To
Long Description Assigned until severity changes to a specific one.
Effect Assigns the selected data-item to the user entered by the caller until the severity matches the specified one.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
User 1 User Input: SingleLineString
User comment 2 User Input: MultiLineString
Target severity 3 User Input: Float
**/USERASSIGNMENT::assignUntilSeverityChangesFrom**
Path User Assignment/Assign Until Severity Changes
Long Description Assigned until severity changes from the current one
Effect Assigns the selected data-item to the user entered by the caller until the severity no-longer matches the current one.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User | 1 | User Input: SingleLineString | | | User comment | 2 | User Input: MultiLineString | | | Severity | 3 | XPath | state/@severity | **/USERASSIGNMENT::assignForTimePeriod**
Path User Assignment/Assign For Time Period
Long Description Assign For Time Period
Effect Assigns the selected data-item to the user entered by the caller until a time period has elapsed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | User | 1 | User Input: SingleLineString | | | User comment | 2 | User Input: MultiLineString | | | Severity | 3 | XPath | state/@severity | | Duration | 4 | User Input: Float | 24 | | Duration units | 5 | User input: Options | - Hours (3600) - Minutes (60) - Days (86400) | **/USERASSIGNMENT::assignUntilDateTime**
Path User Assignment/Assign Until Date /Time
Long Description Assign Until Date / Time
Effect Assigns the selected data-item to the user entered by the caller until a specific date time
The Time argument can also optionally include the time zone region in the form `HH:MM timezoneRegion` (for example, 14:20 Europe/London). If a time zone region is not provided, the Gateway's time zone will be used. The list of supported time zone regions is found in the `date_time_zonespec.csv` file in the Gateway `/resources` directory, provided as part of the Gateway bundle (see [Time Zones and Time Formats](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/geneos_timeformats_tr/index.html) 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 Alert command allows access to additional features of alert manager. **/ALERTS:showAlerts**
Path Show Alerts
Long Description Get information about the alert
Effect Displays configuration information about all the alerts that are applicable for the selected data-item. Alerts are displayed formatted, with a similar display to that used in the Gateway Setup Editor.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell ``` **Arguments** None #### Rule commands Rule commands allow access to additional features of rule manager. **/RULES:showRules**
Path Show Rules
Long Description Get information about the rules.
Effect

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

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

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

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

To view the path, hover over the name of the path alias.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** | Description | Arg | Type | (Default) Value | |-------|-------|-------|-------| | Output format version | 1 | XPath | /geneos/client/features/@RuleShowEx | **/RULES:showVariables**
Path Show Variables
Long Description Get information about the variables available on command target
Effect Displays information about the configured variables available on a target. The command shows the name, type, value, source (either main setup or include file name) and path to where it's configured. Variable values are displayed in a JSON like format to make reading of complex variables easier. For example :

showVariablesExample

All of the macros available at that level of the directory hierachy are shown. These are values that the gateway will fill in for you when used as the value of a variable. Variables defined as a macro are a special given that the Gateway replaces the macro name with a constant. As such there's no meta-data associated with the variable and it isn't possible to show the source or setup path. This isn't such a great issue as the value will be the same no-matter where you define it.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** None **/RULES:ShowRuleContention**
Path Show Rule Contention
Long Description Shows rule targets with more than one rule which may be the cause of rule contention.
Effect Displays a list of rule targets for which there is more than one rule, which can cause rule contention. For each target the rule definition path and file in which it is defined is shown. The target is broken down into a simplified user readable xpath as per the path editor of active console. e.g. gateway/probe/sampler(type=")/dataview/row/column
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** None #### Sampler commands 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 **/PLUGIN:suspend** | | | |-------|-------| | Description | Suspend sampler | | Long Description | Suspends a sampler | | Effect | Temporarily disables sampling for the selected sampler, similar to suspending a sampler via the data quality setting of the Gateway. The sampler's runtime parameter `samplerSuspended` is set to `true`. | **Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(rparam(\"SamplerSuspended\")!=\"true\")] ``` **Arguments** None **/PLUGIN:unsuspend** | | | |-------|-------| | Description | Unsuspend sampler | | Long Description | Unsuspends a sampler | | Effect | Resumes sampling for the selected sampler, if it had been suspended. Suspension may occur due to execution of the suspend sampler command (see above), or as configured in the data quality setting of the Gateway. The sampler's runtime parameter `samplerSuspended` is set to `false`. | **Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(rparam(\"SamplerSuspended\")=\"true\")] ``` **Arguments** None #### Reload commands Reload commands allow reloading the gateway setup file(s). ReloadSetup command is set on the Gateway. Hence, the target XPath for this should be set to /geneos/gateway/directory. It takes on parameter which is optional. If not specified, then all files will be reloaded. If specified, then it will reload the relevant file or group. If you run the command manually you'll see in the dropdown what needs to be specified. In particular, if you want to specify a group of includes you need to put the / after it, as it is in the dropdown. ReloadSetupFile is for the Gateway-includesData plugin, for the file column and looks up the setup file name from the cell value. So, you need to set the target XPath to be the correct cell and specify no parameters. **/GATEWAY:reloadSetup**
Path Reloads selected setup file(s)
Long Description Reloads all or selected gateway setup file(s).
Effect Reloads all or selected gateway setup file(s).
**Targets** ``` /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
File to reload 1 User input: Options All, Main file, All includes, Names of all includes files to select from.
**/GATEWAY:reloadSetupFile**
Path Reloads the include file.
Long Description Reloads the include file whose target path is provided from the Gateway-includesData plugin.
Effect Reloads the include file whose target path is provided from the Gateway-includesData plugin.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-includesData\")]/dataview/rows/row/cell[(@column=\"file\")] ``` **Arguments** None #### Message commands Message commands allow user messaging via the gateway. **/GATEWAY:broadcastMessage**
Path Message Broadcaster
Long Description Sends a ticker event message to all users on this Gateway
Effect Produces a ticker event with the specified severity and message, which is logged and distributed to all connected users via the EventTicker.
**Targets** ``` /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
Message 1 User input: MultiLineString
Message Severity 2 User input: Options OK (1), Warning (2), Critical (3), Undefined (0)
#### Database Logging commands Database commands allow temporary changes to be made to the scope of item value logging as well as pausing or resuming the database connection. **/DATABASELOGGING:itemValues:discard**
Description Discards item value updates from logging.
Long Description The item value updates are discarded and not logged to database. When discarded, the item value updates are lost and cannot be retrieved. This command does not affect the logging of other things such as events, attributes, audit records, etc. to the database.
Effect Item value updates are lost and not logged to database.
**Targets** ``` /geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"false\")] /geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"false\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell ``` **Arguments** None **/DATABASELOGGING:itemValues:log**
Description Resumes logging of item value updates
Long Description Resumes logging of item value updates to the database. In this case, everything is logged to the database (item value updates, events, attributes, audit records, null, etc.).
Effect Item value updates are again logged to database.
**Targets** ``` /geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"true\")] /geneos/gateway/directory[(rparam(\"DBItemValuesDiscarded\")=\"true\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell ``` **Arguments** None **/DATABASELOGGING:connection:pause**
Description Completely pause database logging
Long Description Completely pauses logging of anything (item values, events, attributes, audit records etc) to database. Should be issued when the database is down for maintenance.
Effect Database connection is dropped and nothing is logged to database. However, everything is cached and/or written to dump files, so there is no loss of data. This cached/dumped data can be manually/automatically re-inserted back into the database later using -process-dump-files option or by issuing /DATABASELOGGING:connection:resume command.
**Targets** ``` /geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"false\")] /geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"false\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell ``` **Arguments** None **/DATABASELOGGING:connection:resume**
Description Resumes database logging
Long Description Re-activates logging (of item values, events, attributes etc) to database. Could be issued when the database is up again for re-use after downtime or maintenance.
Effect Database connection (which was earlier paused by issuing /DATABASELOGGING:connection:pause command) is re-established and logging continues as normal. Dump files can be either automatically or manually read to insert data to database.
**Targets** ``` /geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"true\")] /geneos/gateway/directory[(rparam(\"DBConnectionPaused\")=\"true\")]/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-databaseLogging\")]/dataview//cell ``` **Arguments** None #### Netprobe commands **/PROBE:disableSelfAnnouncing**
Description Disables Self Announcing
Long Description Disables Self Announcing mode and updates netprobe setup file
Effect Disables netprobe Self Announcing mode (if configured). Probes remain up and monitoring but will modify their setup files to disable self-announcing mode.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"SelfAnnouncingEnabled\")=\"true\")][(param(\"reverseConnectionRequired\")!=\"true\")] ``` **Arguments** None **/PROBE:disassociate** | | | |-------|-------| | Description | Disassociate a self-announcing Netprobe (SAN) from a Gateway. | | Long Description | Forcibly disassociates a SAN from a Gateway. | | Effect | Forces the probe to be removed from the Gateway. **Caution** If the SAN is up when this command is used, it may connect to a different Gateway. If the SAN does connect to a different Gateway, any snooze or user assignment information is lost. | Only use this command when a self-announcing Netprobe (SAN) has failed, or when the SAN has moved to another Gateway but the original Gateway was not notified. This command is available on SANs with a connection status that is not `Up` or `WaitingForProbe`. It is not available on imported SANs. **Targets** ``` /geneos/gateway/directory/probe[(rparam(\"SelfAnnouncingEnabled\")=\"true\")][(rparam(\"ConState\")!=\"Up\")][(rparam(\"ConState\")!=\"WaitingForProbe\")] ``` **Arguments** None **/PROBE:suspend**
Description Suspend probe
Long Description Suspends connection to a Netprobe
Effect Gateway temporarily disables connection to the selected Netprobe for a period of time, as if the probe had been disconnected by the Data Quality control feature.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"ConState\")!=\"Suspended\")] /geneos/gateway/directory/probe[(rparam(\"ConState\")!=\"Suspended\")]/managedEntity ``` **Arguments** None **/PROBE:unsuspend**
Description Unsuspend probe
Long Description Unsuspends connection to a Netprobe.
Effect Gateway resumes connection to the selected Netprobe, if it had been suspended. Suspension may occur due to execution of the "suspend probe" command (see above), or automatically by the Data Quality feature of gateway.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"ConState\")=\"Suspended\")] /geneos/gateway/directory/probe[(rparam(\"ConState\")=\"Suspended\")]/managedEntity ``` **Arguments** None **/PROBE:refreshDnsAndReconnect** | | | |-------|-------| | Description | Refresh DNS and reconnect probe. | | Long Description | Refresh DNS cache and reconnect a Netprobe. | | Effect | Gateway clears DNS cache for the selected Netprobe and reconnects it by resolving the hostname again. | **Targets** ``` /geneos/gateway/directory/probe /geneos/gateway/directory/probe/managedEntity ``` **Arguments** None #### Collection Agent commands **/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 **/PROBE:suspendImported**
Description Suspend Imported probes
Long Description Suspends importing connection for imported probes
Effect Gateway temporarily disables connection to the exporting gateway that the selected probe was imported from. It is as if the importing connection had been disconnected by the Data Quality control feature.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"ImportedConState\")!=\"Suspended\")][(param(\"Imported\")=\"true\")] /geneos/gateway/directory/probe[(rparam(\"ImportedConState\")!=\"Suspended\")][(param(\"Imported\")=\"true\")]/managedEntity ``` **Arguments** None **/PROBE:unsuspendImported**
Description Unsuspend Imported probes
Long Description Unsuspends importing connection for imported probes
Effect Gateway resumes connection to the exporting gateway that the selected netprobe was imported from, if the connection had been suspended. Suspension may occur due to execution of the "suspend imported probe" command (see above), or automatically by the Data Quality feature of gateway.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"ImportedConState\")=\"Suspended\")][(param(\"Imported\")=\"true\")] /geneos/gateway/directory/probe[(rparam(\"ImportedConState\")=\"Suspended\")][(param(\"Imported\")=\"true\")]/managedEntity ``` **Arguments** None #### Load Monitoring commands Load Monitoring commands allow you to start and stop the collection of statistics on demand, write statistics to file, and reset the statistics collected for the gateway. **/LMSTATS:startLMStatsCollectionNow**
Path Start the collection of load monitoring statistics
Long Description Tells the gateway to start collecting aggregate statistics such as time spent
Effect Starts load monitoring for aggregate statistics
**Targets** ``` /geneos/gateway/directory ``` **Arguments** None **/LMSTATS:startLMStatsCollectionForTimePeriod**
Path Enables the collection of load monitoring statistics for a specified time period.
Long Description Tells the gateway to start collecting aggregate statistics, such as time spent, for a specified time period. It stops collecting statistics automatically when the time period elapses.
Effect Enables the collection of load monitoring statistics for a specified time period
**Targets** ``` /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
Reset Stats before collection 1 User input: Boolean false
Duration 2 User input: Float 24.00
3 User input: Options Hours (3600), Minutes (60), Days (86400)
Write Stats to file after collection 4 User input: Boolean false
Reset Stats after collection 5 User input: Boolean false
Mandatory: No **/LMSTATS:stopLMStatsCollection**
Path Stop the collection of load monitoring statistics
Long Description Tells the gateway to stop collecting aggregate statistics such as time spent
Effect Stops load monitoring for aggregate statistics so that there is less of a hit on the gateway
**Targets** ``` /geneos/gateway/directory ``` **Arguments** None **/LMSTATS:resetLMStats**
Path Reset stats
Long Description Tells the gateway to reset the in-memory load monitoring statistics collected so far.
Effect Resets the time based statistics, so that they can be collected again for analysis over a period of time.
**Targets** ``` /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
No arguments.
**/LMSTATS:writeLMStats**
Path Write statistics
Long Description Requests the gateway to write the collected statistics to disk
Effect The gateway writes the available statistics at the point of receiving this command to disk
**Targets** ``` /geneos/gateway/directory ``` **Arguments** None #### Scheduled Command Data commands Scheduled Command Data commands allow you to view logs and target status of currently running or last run Scheduled Command. **/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWLOG**
Path Shows the Scheduled Command most recent run log.
Long Description Displays the log of the most recent run of the command whose row data-item has been selected. If the command is currently running, this running instance log would be displayed otherwise; the last run instance log (if any) would be displayed.
Effect Views a Scheduled Command run log file. This command allows scope for limiting the amount of data returned.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
**/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:running**
Path Shows the targets and command status against each target of currently running command.
Long Description Displays the targets against which the command is running currently. Also displays the status of the command (SUCCESS/FAIL) against each target.
Effect Displays the targets and command status against each target.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
**/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:scheduled**
Path Shows the targets against which the command will be run in future
Long Description Displays the targets against which the command is scheduled to run in future.
Effect The target XPath(s) is evaluated at every sample, so the targets can change.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
**/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:last**
Path Shows the targets and command status against each target of last run log of command
Long Description Displays the targets against which the command was run most recently in the past. Also displays the status of the command (SUCCESS/FAIL) against each target.
Effect Displays the targets and command status against each target.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandData\")]/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
#### Scheduled Commands History Data commands Scheduled Commands History Data commands allow you to view logs and target status of historic runs of Scheduled Command. **/GATEWAY:SCHEDULEDCOMMANDSHISTORYDATA:VIEWLOG**
Path Shows the Scheduled Command past run log.
Long Description Displays the past timestamp run log of the command whose row data-item has been selected.
Effect Views a Scheduled Command run log file. This command allows scope for limiting the amount of data returned.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandsHistoryData\")]/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
**/GATEWAY:SCHEDULEDCOMMANDSHISTORYDATA:VIEWTARGETS**
Path Shows the targets and command status against each target of past run instance of the command.
Long Description Displays the targets of the past run timestamp of the command whose row DataItem has been selected in the dataview. Also displays the status of the command (SUCCESS/FAIL) against each target.
Effect Displays the targets and command status against each target.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-scheduledCommandsHistoryData\")]/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
#### Diagnostic commands The Create diagnostic command will generate a compressed tar file on the gateway machine where the command is run. The tar file will contain information to enable ITRS to diagnose various issue with the gateway. The tar file contains; - The environment variables passed into the gateway - The gateway setup (including download and history files) - Web diagnostic pages - The gateway caches (snooze, user assignment, licence, setup, persistence, events) - System information (these are gathered by the shell scripts in resources/diagnostics folder. Please see these scripts for more details on what information is gathered The tar file called "diag-.tar.gz", where timestamp is the unix epoch time value in seconds. **/GATEWAY:createDiagnostics**
Path Create Diagnostics
Long Description Creates a compressed tar file containing a set of diagnostic outputs
Effect Obtains a set of data about the gateway and its environment and stores that data in a compressed diagostics tar file.
**Targets** ``` /geneos/gateway/directory ``` **Arguments** None #### Annotation Commands Annotation commands are for viewing annotations. Annotations define name / value pairs for Actions and Effects independent of rules and effect configuration, making it possible to place text specific to data items into an email for example. **/ANNOTATIONS:showAnnotations**
Path Show Annotations
Long Description Show the annotations available
Effect Shows annotations defined for a dataitem. The results are returned in an HTML table.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler/dataview//cell /geneos/gateway/directory/probe/managedEntity/sampler/dataview /geneos/gateway/directory/probe/managedEntity/sampler /geneos/gateway/directory/probe/managedEntity /geneos/gateway/directory/probe /geneos/gateway/directory ``` **Arguments** None #### Rebalance Self-Announcing Netprobes command **/GATEWAY:rebalanceSANs** | | | |-------|-------| | Description | Rebalance Self-Announcing Netprobes | | Long Description | Rebalance Self-Announcing Netprobes connected to this Gateway | | Effect | This command takes a rebalance criterion and a target value. The criterion is either: - `Number of Probes` — the number of Self-Announcing Netprobes (SANs) to remain on the Gateway. - `Score` — the desired score of the Gateway. This command removes SANs that are connected to a Gateway to reduce the number of SANs to the target value, or the Gateway score down to the target value. SANs are not removed if the score would be reduced below the target value. For more information, see [Score](/collection/netprobe/configuration/manage-self-announcing-netprobes/index.html#score ). SANs are removed in the order they connected to the Gateway (the newest SAN is removed first, followed by the second newest, and so on). If removing the next SAN in the order would reduce the score below the target value, no further SANs are removed from the Gateway. SANs are not skipped in the order, even if removing an older SAN would reduce the score and keep it above the target value. This command allows SANs that are removed to find a less busy Gateway to connect to. Therefore, some SANs may return to the Gateway that removed them. **Note** The command may not remove any SANs if the number of SANs if already the target value, or removing a SAN would reduce the Gateway score to below the target value. The default target value is `-1.00`. If this is passed to the command, the command has no effect. | **Targets** ``` /geneos/gateway/directory ``` **Arguments**
Description Arg Type (Default) Value
Rebalance Criterion 1 User input: Options Number of Probes (numOfProbes), Score (score)
Target Value 2 User input: Float -1.00
#### Gateway view busiest command **/GATEWAY:MANAGEDENTITYDATA:VIEWBUSIEST**
Description View Busiest
Long Description Lists dataviews from those with the most cells to the fewest on a Managed Entity.
Effect Lists cells, rows, sampler, and dataview name of each dataview, in order from the dataview with the most cells to the one with the fewest on the Managed Entity.
**Targets** This command is available on the dataviewCount cells of the dataview. **Arguments**
Description Arg Type (Default) Value
Managed Entity name 1 XPath ancestor::managedEntity
#### Gateway Hub Data plug-in command **/GATEWAYHUB:ShowDataviews**
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 **/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 #### ITRS Analytics commands **/IAX:VIEW_METRICS_DROPPED_ISSUES** | | | |-------|-------| | Description | Show metric issues dropped. | | Long Description | Show a table describing which schema-defined metrics have a type mismatch. | | Effect | Show a table of data collected by the Gateway when there is a metric type mismatch when publishing to ITRS Analytics. | **Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-itrsAnalyticsConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsDropped")]/cell[(@column="value")] ``` **Arguments** None **/IAX:VIEW_METRICS_CHANGED_ISSUES** | | | |-------|-------| | Description | Show metric issues changed. | | Long Description | Show a table describing which (schemaless) metrics type have a type mismatch from the last type published to ITRS Analytics. | | Effect | Shows a table of data collected by the Gateway when there is a metric type change when publishing to ITRS Analytics. | **Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-itrsAnalyticsConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsChanged")]/cell[(@column="value")] ``` **Arguments** None **/IAX:CLEAR_METRICS_DROPPED_ISSUES** | | | |-------|-------| | Description | Clear list of metrics issues dropped. | | Long Description | Clear list of metrics issues dropped. | | Effect | Clear the list of dropped metrics issues. This allows for new issues to be added to the list, assuming the previous ones were fixed. | **Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-itrsAnalyticsConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsDropped")]/cell[(@column="value")] ``` **Arguments** None **/IAX:CLEAR_METRICS_CHANGED_ISSUES** | | | |-------|-------| | Description | Clear list of metrics issues changed. | | Long Description | Clear list of metrics issues changed. | | Effect | Clear the list of changed metrics issues. This allows for new issues to be added to the list, assuming the previous ones were fixed. | **Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"Gateway-itrsAnalyticsConnection\")]/dataview[(@name="Summary")]/rows/row[(@name="metricsChanged")]/cell[(@column="value")] ``` **Arguments** None ### Netprobe commands Netprobe commands are provided for use with legacy Netprobes which do not export their own commands. #### Targets for Netprobe commands XPath targets for Netprobe commands are modified with the inclusion of certain parameters. This reduces the possible number of command targets when multiple probes are connected to a Gateway. These parameters include: - The command version number. See [Version number in XPath generation](#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](#rest-service). #### Version number in XPath generation Each plug-in has a group of commands associated with a dataview. This grouping is given a version number. When commands are changed in a plug-in, the version number assigned to the command changes. This version number is used in the XPath for the command. If multiple different probes are connected to a Gateway, multiple XPaths are generated for the command. A different XPath is generated for each different version number the plug-in exposes. #### Control-M plugin ##### /PLUGIN:CONTROL-M:waitingInfo
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 ``` /geneos/gateway/directory/probe/managedEntity/sampler[param("PluginName")="CONTROL-M"]/dataview/rows/row/cell ``` ##### Arguments
Description Arg Type (Default) Value
1 XPath @rowname
#### FKM plug-in **/PLUGIN:FKM:viewTrigger**
Path View File Near this Trigger
Long Description View File Near this Trigger
Effect Views an FKM log file near where the selected trigger was detected.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview/rows/row[contains(@name,\"#\")]/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
2 Static 0
3 Static S
4 Static FileTriggerWatch
5 Static OR
6 Static none
**/PLUGIN:FKM:viewTriggerWithSize**
Path View File Near this Trigger.
Long Description View File Near this Trigger.
Effect Views an FKM log file near where the selected trigger was detected. This is an enhanced version of /PLUGIN:FKM:viewTrigger, allowing the amount of data shown around the trigger to be specified.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler*[(param("PluginName")="FKM")]/dataview[(rparam("ProbeCommandsVersion")="")*]/rows/row[contains(@name,"#")]/cell ``` **Note** For more information on the `` parameter in the XPath, see [XPath generation](#version-number-in-xpath-generation) **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Download size (kb) 2 User input: Integer 2
**/PLUGIN:FKM:triggerDetails**
Path Trigger Details.
Long Description Show details of the triggers that have occurred.
Effect

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

This option is only available when the Sampler's Trigger Mode has been set to Single Grouped Message.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler*[(param("PluginName")="FKM")]/dataview[(rparam("FKM_GROUP_BY_MSG")="true")][(rparam("ProbeCommandsVersion")="")]*/rows/row[contains(@name,"#")]/cell ``` **Note** For more information on the `` parameter in the XPath, see [XPath generation](#version-number-in-xpath-generation) **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
**/PLUGIN:FKM:clearTrigger**
Path Clear this Trigger
Long Description Clear this Trigger
Effect Removes a detected trigger row from the FKM dataview.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview/rows/row[contains(@name,\"#\")]/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
**/PLUGIN:FKM:viewFile**
Path View File
Long Description View File
Effect Views a FKM log file. This command allows scope for filtering the file and limiting the amount of data returned.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview/rows/row[not(contains(@name,\"#\"))]/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
Filter String 4 User input: SingleLineString
5 User input: Options OR, AND
6 User input: SingleLineString
**/PLUGIN:FKM:viewActiveTriggers** | Path | View Active Triggers | |------|----------------------| | Long Description | View Active Triggers | | Effect | Displays information about the selected FKM file row and the active trigger rows currently visible for that file in the dataview. The output is limited to columns visible in the dataview. This command is executed on the Gateway. | **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 | For more information, see [View active triggers in FKM dataview](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/fkm/index.html#view-active-triggers-in-fkm-dataview). **/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](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/fkm/index.html#accept-files-in-fkm-dataview). **/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](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/fkm/index.html#accept-files-in-fkm-dataview). **/PLUGIN:FKM:showTables**
Path Show Tables
Long Description Shows a summary of the keywords FKM is searching for.
Effect Shows a summary of the keywords FKM is searching for.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FKM\")]/dataview//cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static SHOW_TABLES
2 XPath @rowname
#### FTM plug-in **/PLUGIN:FTM:viewFile**
Path View File
Long Description View File
Effect Views a FTM log file. This command allows scope for filtering the file and limiting the amount of data returned.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FTM\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
Filter String 4 User input: SingleLineString
5 User input: Options OR, AND
6 User input: SingleLineString
**/PLUGIN:FTM:acceptFile**
Path Accept File Delay
Long Description Accept File Delay for the selected file
Effect Accept a files delay. Changes delay to zero followed by a comment with the actual delay.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FTM\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
#### GL-SLE plug-in **/PLUGIN:GL-SLE:accept**
Path Accept
Long Description GL-SLE:Accept Unacked Orders
Effect Removes an unacknowledged order row from the GL-SLE dataview.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"GL-SLE\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$ACCEPT_UNACKED_SLE_ORDERS
#### PROCESSES plug-in **/PLUGIN:PROCESSES:startWithoutPassword**
Path Start Process
Long Description PROCESSES: Start Process
Effect Starts a process using the configured start process script, on a Netprobe which does not require authentication.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"salt\")=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row[not(contains(@name,\"#\"))]/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
2 Static none
**/PLUGIN:PROCESSES:stopWithoutPassword**
Path Stop Process
Long Description PROCESSES: Stop Process
Effect Stops a process using the configured stop process script, on a Netprobe which does not require authentication.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"salt\")=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row[not(contains(@name,\"#\"))]/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
2 Static none
Do not auto-restart 3 User input: Boolean false
**/PLUGIN:PROCESSES:startWithPassword**
Path Start Process
Long Description PROCESSES: Start Process
Effect Starts a process using the configured start process script, on a Netprobe which requires authentication.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"salt\")!=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell[not(contains(@rowname,\"#\"))] ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Enter Password 2 User input: SingleLineString
**/PLUGIN:PROCESSES:stopWithPassword**
Path Stop Process
Long Description PROCESSES: Stop Process
Effect Stops a process using the configured stop process script, on a Netprobe which requires authentication.
**Targets** ``` /geneos/gateway/directory/probe[(rparam(\"salt\")!=\"\")]/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell[not(contains(@rowname,\"#\"))] ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Enter Password 2 User input: SingleLineString
Do not auto-restart 3 User input: Boolean false
**/PLUGIN:PROCESSES:details**
Path View details of this Process
Long Description PROCESSES: View details of this Process
Effect Produces a summary of the selected process at the time when the command was executed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$PROCINFO
2 XPath @rowname
**/PLUGIN:PROCESSES:log**
Path View log file
Long Description PROCESSES: View log file
Effect Views the configured log file for the selected process. This command allows scope for filtering the file and limiting the amount of data returned.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 XPath @rowname
Initial Download size (kb) 2 User input: Integer 2
Delivery Type 3 User input: Options Snapshot (S), Continuous (D)
Filter String 4 User input: SingleLineString
5 User input: Options OR, AND
6 User input: SingleLineString
**/PLUGIN:PROCESSES:top20Processes**
Path Top 20 Processes
Long Description View Top 20 Processes
Effect isplays a summary for the top 20 processes in order of CPU usage.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]//cell /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")] ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static 20
**/PLUGIN:PROCESSES:allProcesses**
Path All Processes
Long Description View All Processes
Effect Displays a summary for all processes in order of CPU usage.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")]//cell /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"PROCESSES\")] ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static -1
#### WTS-SESSIONS plug-in **/PLUGIN:WTS-SESSIONS:viewProcesses**
Path View Processes
Long Description WTS-SESSIONS:View Processes
Effect Produces a summary of all terminal services processes at the time when the command was executed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static DETAILS
Mandatory: No **/PLUGIN:WTS-SESSIONS:send**
Path Send
Long Description WTS-SESSIONS:Send
Effect Sends the selected user a message.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type (Default) Value
Enter Message 1 User input: MultiLineString
**/PLUGIN:WTS-SESSIONS:logoff**
Path Logoff
Long Description WTS-SESSIONS:Logoff
Effect Logs off the selected user.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell ``` **Arguments** None **/PLUGIN:WTS-SESSIONS:ping**
Path Ping
Long Description WTS-SESSIONS:Ping
Effect Attempts to ping the remote host of the selected user and displays the results.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static PING
**/PLUGIN:WTS-SESSIONS:tracert**
Path Trace route
Long Description WTS-SESSIONS:Trace route
Effect Attempts to trace a route across the network to the remote host of the selected user and displays the results.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type Default) Value
1 Static TRACERT
#### WTS-PROCESSES plug-in **/PLUGIN:WTS-PROCESSES:killProcess**
Path Kill Process
Long Description WTS-PROCESSES:Kill Process
Effect Kills the selected terminal process.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WTS-PROCESSES\")]/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static KILL
#### CITRIX-SESSIONS plug-in **/PLUGIN:CITRIX-SESSIONS:viewProcesses**
Path View Processes
Long Description CITRIX-SESSIONS:View Processes
Effect Produces a summary of all Citrix hosted processes at the time when the command was executed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static DETAILS
**/PLUGIN:CITRIX-SESSIONS:send**
Path Send
Long Description CITRIX-SESSIONS:Send
Effect Sends the selected user a message.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type (Default) Value
Enter Message 1 User input: MultiLineString
**/PLUGIN:CITRIX-SESSIONS:logoff**
Path Logoff
Long Description CITRIX-SESSIONS:Logoff
Effect Logs off the selected user.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell ``` **Arguments** None **/PLUGIN:CITRIX-SESSIONS:ping**
Path Ping
Long Description CITRIX-SESSIONS:Ping
Effect Attempts to ping the remote host of the selected user and displays the results.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static PING
**/PLUGIN:CITRIX-SESSIONS:tracert**
Path Trace route
Long Description CITRIX-SESSIONS:Trace route
Effect Attempts to trace a route across the network to the remote host of the selected user and displays the results.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-SESSIONS\")]//cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static TRACERT
#### CITRIX-PROCESSES plug-in **/PLUGIN:CITRIX-PROCESSES:killProcess**
Path Kill Process
Long Description CITRIX-PROCESSES:Kill Process
Effect Kills the selected terminal process.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CITRIX-PROCESSES\")]/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static KILL
#### RMC-INTERFACE plug-in Beginning Geneos 5.1.1, internal commands for the RMC Interface plugin have been removed and are no longer supported. #### LATENCY-RTT plug-in **/PLUGIN:LATENCY-RTT:clearLostMessages**
Path Clear
Long Description LATENCY-RTT:Clear Lost Messages
Effect Clears the Lost Messages list in the plug-in
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*LATENCY-RTT*\")]/dataview/headlines/cell[(@name=\"lostMessages\")] ``` **Arguments** None **/PLUGIN:LATENCY-RTT:clearMisdirectedMessages**
Path RTT:clearMisdirectedMessages Clear
Long Description LATENCY-RTT:Clear Misdirected Messages
Effect Clears the Misdirected Messages list in the plug-in
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*LATENCY-RTT*\")]/dataview/headlines/cell[(@name=\"misdirectedMessages\")] ``` **Arguments** None **/PLUGIN:LATENCY-RTT:clearCyclicMessages**
Path Clear
Long Description LATENCY-RTT:Clear Cyclic Messages
Effect Clears the Cyclic Messages list in the plug-in
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*LATENCY-RTT*\")]/dataview/headlines/cell[(@name=\"cyclicMessages\")] ``` **Arguments** None #### HARDWARE plug-in **/PLUGIN:HARDWARE:top20Processes**
Path Top 20 Processes
Long Description View Top 20 Processes
Effect Displays a summary for the top 20 processes in order of CPU usage.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")]//cell /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")] ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static 20
**/PLUGIN:HARDWARE:allProcesses**
Path All Processes
Long Description View All Processes
Effect Displays a summary for all processes listed in order of CPU usage.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")]//cell /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"HARDWARE\")] ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static -1
#### CPU plug-in **/PLUGIN:CPU:top20Processes**
Path Top 20 Processes
Long Description View Top 20 Processes
Effect Displays a summary for the top 20 processes in order of CPU usage.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")]//cell /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")] ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static 20
**/PLUGIN:CPU:allProcesses**
Path All Processes
Stderr Type SingleLineString
Effect Displays a summary for all processes listed in order of CPU usage.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")]//cell /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"CPU\")] ``` **Arguments**
Description Arg Type (Default) Value
1 Static $$$TOPCPU
2 Static -1
#### PATS-TRADING-BREACHES plug-in **/PLUGIN:PATS-TRADING-BREACHES:acknowledge**
Description Acknowledge
Long Description PATS-TRADING-BREACHES:Acknowledge Breach
Effect Acknowledges a Trading Breach.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"PATS-TRADING-BREACHES*\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static ACKNOWLEDGE
2 XPath @rowname
**/PLUGIN:PATS-TRADING-BREACHES:remove**
Description Remove
Long Description PATS-TRADING-BREACHES:Remove Breach
Effect Removes a Trading Breach.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"PATS-TRADING-BREACHES*\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static REMOVE
2 XPath @rowname
**/PLUGIN:PATS-TRADING-BREACHES:details**
Description View Details
Long Description PATS-TRADING-BREACHES:View Details
Effect Shows the details of a Trading Breach.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"PATS-TRADING-BREACHES*\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static REACH_DETAILS
2 XPath @rowname
#### E4JMS-QUEUES plug-in **/PLUGIN:E4JMS-QUEUES:showMessages**
Description Show Messages
Long Description E4JMS-QUEUES:showUsers
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*E4JMS-QUEUES*\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static showUsers
2 XPath @rowname
#### E4JMS-TOPICS plug-in **/PLUGIN:E4JMS-TOPICS:showUsers**
Description Show Users
Long Description E4JMS-TOPICS:showUsers
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[wild(param(\"PluginName\"),\"*E4JMS-TOPICS*\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static showUsers
2 XPath @rowname
#### TIB-RV plug-in **/PLUGIN:TIB-RV:acceptError**
Description Accept Error
Long Description Accepts an error
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"ERROR\")]/parent::node()/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static ACCEPT_ERROR
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]
**/PLUGIN:TIB-RV:acceptWarning**
Description Accept Warning
Long Description Accepts a warning
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"WARNING\")]/parent::node()/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static ACCEPT_WARNING
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]
**/PLUGIN:TIB-RV:acceptInfo**
Description Accept Info
Long Description Accepts an Info
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"INFO\")]/parent::node()/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static ACCEPT_INFO
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]
**/PLUGIN:TIB-RV:acceptRvdDown**
Description Accept RVD down
Long Description Accepts an RVD down
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"TIB-RV\")]/dataview[(@name=\"HOSTS\")]/rows/row/cell[(@column=\"status\")][(@value=\"RVD down\")]/parent::node()/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static ACCEPT_RVD_DOWN
2 XPath @rowname
3 XPath ../cell[@column='address'][@value]
#### WIN-SERVICES plug-in **/PLUGIN:WIN-SERVICES:startService**
Description Start Service
Long Description Starts the selected service
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WIN-SERVICES\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static START_SERVICE
2 XPath @rowname
**/PLUGIN:WIN-SERVICES:stopService**
Description Stop Service
Long Description Stops the selected service
Effect
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"WIN-SERVICES\")]/dataview/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
1 Static STOP_SERVICE
2 XPath @rowname
#### FLM plug-in **/PLUGIN:FLM:clearFeed**
Path Clear all peaks
Long Description Clears all peak latency values for this feed
Effect This command clears (removes) all peak rows which have been created for the selected feed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell ``` **Arguments**
Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static CLEAR_FEED
Row name 3 XPath @rowname
**/PLUGIN:FLM:clearPeak**
Path Clear this peak
Long Description Clears this peak latency value from this feed
Effect This command clears (removes) the selected peak row.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[contains(@name,\"#\")]/cell ``` **Arguments**
Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static CLEAR_PEAK
Row name 3 XPath @rowname
**/PLUGIN:FLM:verifyFeed**
Path Latency report
Long Description Show feed latency for the last X minutes
Effect This command produces an HTML report which displays a period of market data up to 30 minutes, matched against data received from the baseline feed.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell ``` **Arguments**
Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static REPORT_VERIFY
Row name 3 XPath @rowname
Report interval (minutes) 4 User input: Integer 5
Start Time (optional) 5 User input: SingleLineString HH:MM
**/PLUGIN:FLM:verifyFeedPeak**
Path Latency report (peak)
Long Description Show feed latency report for the selected peak
Effect This command is issued on a peak row, and produces a similar report to the /PLUGIN:FLM:verifyFeed command. The difference is that rather than the latest X minutes, the resulting report contains (by default) 6 minutes of latency data centred around the time of the tick which produced the peak row (highlighted in red on the report).
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[contains(@name,\"#\")]/cell ``` **Arguments**
Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static REPORT_VERIFY_PEAK
Row name 3 XPath @rowname
**/PLUGIN:FLM:reportFeed**
Path Recent-ticks report
Long Description Report on ticks received in the last X minutes
Effect The recent ticks report command produces an HTML report detailing the ticks received in the last X minutes.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell ``` **Arguments**
Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static REPORT_RECENT
Row name 3 XPath @rowname
Report interval (minutes) 4 User input: Integer 5
**/PLUGIN:FLM:history**
Path Show tick history
Long Description Shows a filtered listing of received tick data
Effect This command displays an output of the FLM tick history file displaying ticks as they are collected from the feeds.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param(\"PluginName\")=\"FLM\")]/dataview[(@name=\"LATENCY\")]/rows/row[not(contains(@name,\"#\"))]/cell ``` **Arguments**
Description Arg Type (Default) Value
Legacy parameter 1 Static
Command type 2 Static TICK_HISTORY
Row name 3 XPath @rowname
Initial download size (kb) 4 User input: Integer 10
Delivery Type 5 User input: Options Snapshot (S), Continuous (D)
Feed (use * for wildcards) 6 User input: SingleLineString
Add Baseline Feed 7 User input: Boolean true
Filter (specify 'record.field';use * for wildcards) 8 User input: SingleLineString
#### Message Tracker plug-in **/PLUGIN:MESSAGE-TRACKER:ClearAll**
Path Lost Messages/Clear All
Long Description Clear All Messages
Effect This command will remove all messages from the Lost Messages view and reset the count headline to 0.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]/dataview[@name='Lost'] /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Lost']//cell ``` **Arguments** None **/PLUGIN:MESSAGE-TRACKER:ClearCheckpoint**
Path Lost Messages/Clear this Checkpoint
Long Description Clear All Messages for this Checkpoint
Effect This command will remove all lost messages that were last seen at the specified checkpoint.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Lost']/rows/row/cell[@column='lastCheckpointVisited'] ``` **Arguments**
Description Arg Type (Default) Value
Checkpoint name 1 XPath @value
**/PLUGIN:MESSAGE-TRACKER:ClearMessage**
Path Lost Messages/Clear Message
Long Description Clear this Message
Effect This command will remove a single message.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Lost']/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
Row name 1 XPath @rowname
Failure type 2 XPath ../cell[@column='failureType']/@value
Checkpoint name 3 XPath ../cell[@column='lastCheckpointVisited']/@value
**/PLUGIN:MESSAGE-TRACKER:ClearAllSlow**
Path Slow Messages/Clear All
Long Description Clear All Messages
Effect This command will remove all messages from the Slow Messages view and reset the count headline to 0.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]/dataview[@name='Slow'] /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Slow']//cell ``` **Arguments**
Description Arg Type (Default) Value
No arguments
**/PLUGIN:MESSAGE-TRACKER:ClearCheckpointSlow**
Path Slow Messages/Clear this Checkpoint
Long Description Clear All Messages for this Checkpoint
Effect This command will remove all slow messages that were last seen at the specified checkpoint.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Slow']/rows/row/cell[@column='problemAt'] ``` **Arguments**
Description Arg Type (Default) Value
Checkpoint name 1 XPath @value
**/PLUGIN:MESSAGE-TRACKER:ClearMessageSlow**
Path Slow Messages/Clear Message
Long Description Clear this Message
Effect This command will remove a single message.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Slow']/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
Row name 1 XPath @rowname
Failure type 2 XPath ../cell[@column='failureType']/@value
Checkpoint name 3 XPath ../cell[@column='lastCheckpointVisited']/@value
**/PLUGIN:MESSAGE-TRACKER:ClearAllUnacknowledged**
Path Unacknowledged Messages/Clear All
Long Description Clear All Messages
Effect This command will remove all messages from the Unacknowledged Messages view.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]/dataview[@name='Unacknowledged'] /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name=' Unacknowledged']//cell ``` **Arguments**
Description Arg Type (Default) Value
No arguments
**/PLUGIN:MESSAGE-TRACKER:ClearCheckpointUnacknowledged**
Path Unacknowledged Messages/Clear this Checkpoint
Long Description Clear All Messages for this Checkpoint
Effect This command will remove all unacknowledged messages that were last seen at the specified checkpoint.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Unacknowledged']/rows/row/cell[@column='lastCheckpointVisited'] ``` **Arguments**
Description Arg Type (Default) Value
Checkpoint name 1 XPath @value
**/PLUGIN:MESSAGE-TRACKER:ClearMessageUnacknowledged**
Path Unacknowledged Messages/Clear Message
Long Description Clear this Message
Effect This command will remove a single message
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='MESSAGE-TRACKER')]//dataview[@name='Unacknowledged']/rows/row/cell ``` **Arguments**
Description Arg Type (Default) Value
Row name 1 XPath @rowname
Failure type 2 XPath ../cell[@column='failureType']/@value
Checkpoint name 3 XPath ../cell[@column='lastCheckpointVisited']/@value
#### Prometheus Query plugin **/PLUGIN:PROMETHEUS-QUERY:showQuery** | | | |-------|-------| | Description | Show Query| | Effect | Displays the PromQL query executed for the dataview, as specified in the query configuration. | **Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler[(param('PluginName')='PROMETHEUS-QUERY')]/dataview/headlines/cell ``` **Arguments** No arguments. #### Sampler commands **/PLUGIN:viewSetup**
Description View Setup
Long Description View Setup
Effect Displays the setup for the selected sampler. This command shows both the XML setup, and the legacy converted setup. The encoded password ("AES 256 bit encryption" or "std encoded") are masked and their value is replaced with "xxx". The plaintext password are not masked.
**Targets** ``` /geneos/gateway/directory/probe/managedEntity/sampler ``` **Arguments**
Description Arg Type (Default) Value
No arguments.
**/PLUGIN:lastSampleInfo**
Description Last Sample Info
Long Description Last Sample Information
Effect Displays information on when the sampler last sampled.
**Targets** ``` /geneos/gateway/directory/probe[(param(\"Virtual\")!=\"true\")]/managedEntity/sampler/dataview ``` **Arguments**
Description Arg Type (Default) Value
No arguments.
#### Netprobe commands **/PROBE:viewLog**
Description View Netprobe Log
Long Description View Netprobe Logfile
Effect Views the Netprobe log file (if configured). This command allows scope for filtering the file and limiting the amount of data returned.
**Targets** ``` /geneos/gateway/directory/probe[(rparam("ConState")!="Down")]/managedEntity/sampler /geneos/gateway/directory/probe[(rparam("ConState")!="Down")]/managedEntity /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 **/RMS:putFile**
Description Put File
Long Description Puts a file to Netprobe from the Gateway
Effect Copies a file from Gateway to Netprobe using RMS functionality.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
Src Filename (Gateway) 1 User input: SingleLineString
Dst Filename (Probe) 2 User input: SingleLineString
**/RMS:getFile**
Description Get File
Long Description Gets a file from Netprobe and sends it to the Gateway
Effect Copies a file from Netprobe to Gateway using RMS functionality.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
Src Filename (Probe) 1 User input: SingleLineString
Dst Filename (Gateway) 2 User input: SingleLineString
**/RMS:putProbe**
Description Put Probe
Long Description Puts a netprobe binary file to Netprobe from the Gateway
Effect Copies a netprobe binary file from Gateway to Netprobe using RMS functionality.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
Src Filename (Gateway) 1 User input: SingleLineString
**/RMS:restart**
Description Restart
Long Description Restarts the probe
Effect Restarts the Netprobe process.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
1 Static $RESTART
**/RMS:rollback**
Description Rollback
Long Description Roll back to an old version of the probe
Effect Rolls back an older version of the Netprobe. This is typically used after failure of an /rms/upgrade command to remove the failed upgrade binary.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
1 Static $ROLLBACK
**/RMS:upgrade**
Description Upgrade
Long Description Prepare the probe for upgrading
Effect Prepares a netprobe for an upgrade by making a backup of the current binary. Used in conjunction with the /rms/rollback command for failed upgrades.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
1 Static $UPGRADE
**/RMS:shutdown**
Description Shutdown
Long Description Shutdown the probe
Effect Shuts down the probe by exiting the Netprobe process.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
1 Static $SHUTDOWN
**/RMS:launch**
Description Launch
Long Description Launch a command on the probe
Effect Launches a command on the Netprobe and then returns immediately.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
1 Static $LAUNCH
Command 2 User input: SingleLineString
**/RMS:exec**
Description Exec
Long Description Exec a command on the probe
Effect Executes a command on the Netprobe and collects the output.
**Targets** ``` /geneos/gateway/directory/probe ``` **Arguments**
Description Arg Type (Default) Value
Command 1 User input: SingleLineString
#### Hot Standby Commands **/GATEWAY:failback**
Description Manual Failback
Long Description Manual Failback
Effect Releases control to back to the primary gateway in a hot standby pair.
**Targets** ``` /geneos/gateway/directory[(param(\"HotStandbyRole\")=\"Secondary\")][(param(\"HotStandbyManualFailbackActive\")=\"true\")][(rparam(\"HotStandbyState\")=\"Active\")] ``` **Arguments** None