SSHCommand probe

A probe using the ECC queue topic name SSHCommand executes a shell command on the target host, and returns the resulting output to the sensor.

Discovery supports Bourne Shell (sh) and Bourne-again Shell (bash) commands. Enter shell script commands in the probe's ECC queue name field. The shell script can use variables and file operations supported by the target UNIX shell.

  • ServiceNow SSH: The SSH engine that is active by default on new instances.
  • Customers on upgraded instances can manually enable ServiceNow SSH for a particular probe by setting the use_snc_ssh parameter to true. Alternatively, enable it for all probes on the MID Server by setting the MID Server parameter mid.ssh.use_snc to true.

SSHCommand parameters

Several parameters are available for the SSHCommand probe.

For instructions on configuring probe parameters, see Set probe parameters.

Table 1. Parameters Table
Parameter Description
allow_unsupported_shells Allows a probe designer to attempt to run a command on a device that does not have a supported shell. With no shell, the following is true:
  • No path information can be provided.
  • No scripts can function, because there is no ability to handle script parameters.
  • The text that is specified in the ECC queue name field of the probe form is the raw command that is run on the device.

For example, you may design a probe to display the version of a Cisco switch running NX-OS. The command that the switch understands is show version. To accomplish this, put the show version command in the ECC queue name field, and add the parameter name allow_unsuported_shells with a value of true.

This parameter is only effective for sncssh. It is not supported with j2ssh. Currently supported shells are sh, bash, ksh, csh, and tcsh.

  • Type: string, true or false
  • Default value: false
source [Required] Specifies the initial host to connect to.
  • Type: string (URL)
  • Default value: None
port Specifies the target port to connect to.
  • Type: integer (port)
  • Default value: 22
debug Specifies whether to write SSH debug information to the log file. The parameter usage depends on whether the ServiceNow SSH client is enabled.
When the ServiceNow SSH client is enabled, this parameter functions as follows:
  • Type: string
  • Default value: false
    The following string values are valid for the ServiceNow SSH client:
    • true: Enables SSH debug information in the log file.
    • false: Disables SSH debug information in the log file.
    • <IP Addresses>: Specifies which IP ranges to enable SSH debug information in the log file. You can enter IP addresses in the following formats:
      • An IP range defined by a slash and the number of bits in the subnetwork. For example, the string 10.10.10.0/24 scans 24 bits of IP addresses from 10.10.10.0 to 10.10.10.254.
      • An IP range defined by a dash. For example, the string 10.10.11.0-10.10.11.165 scans the IP addresses from 10.10.11.0 to 10.10.11.165.
      • A comma-separated list of specific IP addresses. For example the string 10.10.11.200,10.10.11.235 scans the IP addresses 10.10.11.200 and 10.10.11.235.
    • deferred: Specifies to log SSH debug information in memory unless an error or warning occurs. If an error or warning occurs, the platform publishes the debug information to the log file. This ensures that only the part of the log file pertaining to the error or warning is recorded. If no error or warning is detected, the platform deletes the unused log data from memory when the session closes. Each session stores up to 1000 log messages. If the session exceeds 1000 log messages, the deferred log discards the oldest log message to make room for the newest log message.
When the ServiceNow SSH client is disabled, this parameter enables or disables SSH debug information in the log file:
  • Type: true | false
  • Default value: false
debug_ssh Specifies whether the legacy SSH client writes debug information into the agent/logs/ssh.log log file. This log file can get very large and should be reviewed frequently.
The ServiceNow SSH client does not use this parameter.
  • Type: true | false
  • Default value: false
timeout Sets the socket connection timeout for the legacy SSH client.
The ServiceNow SSH client does not use this parameter.
  • Type: integer (milliseconds)
  • Default value: 60,000
path_override Specifies how to change the default paths set before executing a command. Type one or more override paths delimited by a colon (:). The default path is /usr/sbin: /usr/bin: /bin: /sbin.
The ServiceNow SSH client accepts the following prefixes in front of the path_overide value:
  • append: Appends the override path to the end of the host’s path. This is the default behavior.
  • replace: Replaces the host path with the path_overide value.
  • prepend: Appends the override path to the front of the host path.
  • Type: string (a colon-separated list of directories)
  • Default value: None
keyboard_interactive Determines whether to enforce keyboard_interactive SSH login mode.
  • Type: true | false
  • Default value: false
must_sudo Determines whether SSH commands run through sudo.
  • Type: true | false
  • Default value: false
run_in_terminal Determines whether SSH commands run in an SSH terminal.
  • Type: true | false
  • Default value:
    • ServiceNow SSH client: false
    • Legacy SSH client: true
set_path Determines whether the probe is allowed to alter the session's PATH variable or not. By default, during session setup, the PATH variable is set to /usr/sbin:/usr/bin:/bin:/sbin.
  • Type: true | false
  • Default value: true
rm_override Overrides the default remove command (/bin/rm -f) with the provided value.
  • Type: string
  • Default value: none
use_snc_ssh Enables the ServiceNow SSH client. The ServiceNow SSH client is active by default. Enabling the ServiceNow SSH client disables the legacy SSH client.
  • Type: true | false
  • Default value: false
command_timeout_ms Number of milliseconds an SSH command is allowed to run before timing out (default is configurable per MID server).
The legacy SSH client does not use this parameter.
  • Type: integer
  • Default value: value of the mid.ssh.command_timeout_ms MID Server parameter.
preserve_sudo_environment Specifies whether to use sudo to preserve the environment for SSH. This parameter is only effective if the sudo environment on the host being probed supports the -E switch.
  • Type: true | false
  • Default value: false

SSHCommand path

The SSHCommand probe computes the default path from the following sources.

  • MID Server parameter: mid.ssh.path_override
  • SSH Command probe parameter: path_override
  • User's default path: Shell configuration file

If you set the MID Server path override parameter, Discovery appends this path to the default path. If you set the probe path parameter, Discovery uses this path instead of the default path. Discovery always appends a user's default execution path to the MID Server and probe parameter paths.

Default Path

By default, the MID Server searches for SSH commands in the following paths:
  • /usr/sbin
  • /usr/bin
  • /bin
  • /sbin

Shell script options

The SSHCommand probe supports the following scripting options in the ECC queue name field.

Table 2. Shell Scripting Options Table
Summary Syntax Description
Variable ${variable} Replaces the token with the value of the variable. For example, ${catalina_home} specifies the installation location of a Tomcat server.
Include File ${File:file_name.sh} Treats the contents of the specified file as a shell script. For example, ${File:findcat.sh} runs the findcat shell script.