Gateway Commands

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.

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

#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"}	

Run commands

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

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

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

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

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

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

{
	"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"
}

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

{ "status":"finished" }

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

{ "status":"finished" }

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

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

List commands

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

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

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

{
	"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"
				}
			]
		}
	]
}

{
"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.

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

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

{
	"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\")]"
	]
}

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

Validate the Gateway setup

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

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

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

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

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

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

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

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

Obtain the Gateway time zone and offset

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

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

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

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

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

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

Response

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

Authorise SSO User

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

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

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

Curl Command

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

SSO Agent Response

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

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

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

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

HTTP Status codes

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

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

HTTPS Connections

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

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

User Authentication

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

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

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

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

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

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

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

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

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

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

Configuration

Snooze until command

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

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

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

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

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

There are 3 versions of /SNOOZE:until command:

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

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

/SNOOZE:until

Targets

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

Arguments

/SNOOZE:untilAllMe

Targets

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

Arguments

/SNOOZE:untilAllMeCell

Targets

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

Arguments

User Assignment commands

Runs command that allow control over the user assignment functionality.

/USERASSIGNMENT:unassign

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

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

/USERASSIGNMENT:info

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

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

/USERASSIGNMENT:assign

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

/USERASSIGNMENT::assignUntilSeverityChangesTo

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

/USERASSIGNMENT::assignUntilSeverityChangesFrom

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

/USERASSIGNMENT::assignForTimePeriod

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

/USERASSIGNMENT::assignUntilDateTime

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

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

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

/USERASSIGNMENT::assignUntilSeverityChangeOrTimePeriod

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

/USERASSIGNMENT::assignUntilValueChanges

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

/USERASSIGNMENT:unassignAbsentItems

Targets

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

Arguments

/USERASSIGNMENT:assignUntilOk

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

Alert commands

Alert command allows access to additional features of alert manager.

/ALERTS:showAlerts

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

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

/RULES:showVariables

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

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

Targets

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

Arguments

None

Reload commands

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

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

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

/GATEWAY:reloadSetup

Targets

/geneos/gateway/directory

Arguments

/GATEWAY:reloadSetupFile

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

Targets

/geneos/gateway/directory

Arguments

Reporting commands

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

/REPORT:generateRun

Targets

/geneos/gateway/directory

Arguments

/REPORT:deleteRuns

Targets

/geneos/gateway/directory

Arguments

Netprobe commands

/PROBE:disableSelfAnnouncing

Targets

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

Arguments

None

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

/PROBE:suspend

Targets

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

Arguments

None

/PROBE:unsuspend

Targets

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

Arguments

None

Gateway Sharing commands

/PROBE:suspendImported

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

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

Targets

/geneos/gateway/directory

Arguments

None

/LMSTATS:startLMStatsCollectionForTimePeriod

Targets

/geneos/gateway/directory

Arguments

Mandatory: No

/LMSTATS:stopLMStatsCollection

Targets

/geneos/gateway/directory

Arguments

None

/LMSTATS:resetLMStats

Targets

/geneos/gateway/directory

Arguments

/LMSTATS:writeLMStats

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

Targets

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

Arguments

/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:running

Targets

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

Arguments

/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:scheduled

Targets

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

Arguments

/GATEWAY:SCHEDULEDCOMMANDDATA:VIEWTARGETS:last

Targets

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

Arguments

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

Targets

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

Arguments

/GATEWAY:SCHEDULEDCOMMANDSHISTORYDATA:VIEWTARGETS

Targets

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

Arguments

Diagnostic commands

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

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

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

/GATEWAY:createDiagnostics

Targets

/geneos/gateway/directory

Arguments

None

/ANNOTATIONS/ShowAnnotations

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

FKM plug-in

/PLUGIN:FKM:viewTrigger

Targets

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

Arguments

/PLUGIN:FKM:viewTriggerWithSize

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

Arguments

/PLUGIN:FKM:triggerDetails

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

Arguments

/PLUGIN:FKM:clearTrigger

Targets

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

Arguments

/PLUGIN:FKM:viewFile

Targets

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

Arguments

/PLUGIN:FKM:acceptFile

Targets

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

Arguments

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

/PLUGIN:FKM:acceptFileMulti

Targets

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

Arguments

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

/PLUGIN:FKM:showTables

Targets

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

Arguments

FTM plug-in

/PLUGIN:FTM:viewFile

Targets

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

Arguments

/PLUGIN:FTM:acceptFile

Targets

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

Arguments

WTS-SESSIONS plug-in

/PLUGIN:WTS-SESSIONS:viewProcesses

Targets

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

Arguments

Mandatory: No

/PLUGIN:WTS-SESSIONS:send

Targets

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

Arguments

/PLUGIN:WTS-SESSIONS:logoff

Targets

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

Arguments

None

/PLUGIN:WTS-SESSIONS:ping

Targets

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

Arguments

/PLUGIN:WTS-SESSIONS:tracert

Targets

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

Arguments

WTS-PROCESSES plug-in

/PLUGIN:WTS-PROCESSES:killProcess

Targets

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

Arguments

CITRIX-SESSIONS plug-in

/PLUGIN:CITRIX-SESSIONS:viewProcesses

Targets

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

Arguments

/PLUGIN:CITRIX-SESSIONS:send

Targets

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

Arguments

/PLUGIN:CITRIX-SESSIONS:logoff

Targets

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

Arguments

None

/PLUGIN:CITRIX-SESSIONS:ping

Targets

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

Arguments

/PLUGIN:CITRIX-SESSIONS:tracert

Targets

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

Arguments

CITRIX-PROCESSES plug-in

/PLUGIN:CITRIX-PROCESSES:killProcess

Targets

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

Arguments

RMC-INTERFACE plug-in

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

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

LATENCY-RTT plug-in

/PLUGIN:LATENCY-RTT:clearLostMessages

Targets

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

Arguments

None

/PLUGIN:LATENCY-RTT:clearMisdirectedMessages

Targets

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

Arguments

None

/PLUGIN:LATENCY-RTT:clearCyclicMessages

Targets

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

Arguments

None

WIN-SERVICES plug-in

/PLUGIN:WIN-SERVICES:startService

Targets

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

Arguments

/PLUGIN:WIN-SERVICES:stopService

Targets

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

Arguments

FLM plug-in

/PLUGIN:FLM:clearFeed

Targets

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

Arguments

/PLUGIN:FLM:clearPeak

Targets

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

Arguments

/PLUGIN:FLM:verifyFeed

Targets

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

Arguments

/PLUGIN:FLM:verifyFeedPeak

Targets

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

Arguments

/PLUGIN:FLM:reportFeed

Targets

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

Arguments

/PLUGIN:FLM:history

Targets

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

Arguments