Skip to content

ExecuteCommand (V7.3 and earlier)

Miriam McMahon edited this page Sep 1, 2023 · 1 revision

Description

An alternate method for connecting to a remote host using SSH. This does not allocate a pseudo-terminal so it can only be used to execute a command that does not prompt for user input. The output from the command is made available in the selected BufferName variable. An exception is thrown if any error output is produced by the command.
Disconnect should be used to close the connection when it is no longer required.

Note: This method is only supported for SSH connections.
Send and Receive cannot be used on a connection object opened using ExecuteCommand.

Compatibility

This command was introduced in Safeguard 2.11
In versions < 6.13, the remote SSH server on windows may impose a limit on the quantity of output returned for a single command.

Parameters

Parameter Name Description Type Resolved Type Required
ConnectionObjectName The variable name that identifies the connection. A new connection will be made if not already connected Value String Yes
NetworkAddress The network address of the target host Value String Yes
Port Optional Port number. If not specified, the default SSH port will be used Value Integer No
Login The login name to use for the connection Value String Yes
Password The login password to use for the connection, if password authentication is required Value String No
UserKey The user's public key to authenticate, if SSH key authentication is required Value String No
HostKey The host key which will be compared with that reported by the remote host, if CHeckHostKey=true Value String No
CheckHostKey If true, compare the HostKey with the one provided by the remote server Value Boolean No
AutoAdjustCiphers Adjust or not the list of Ciphers when connecting to the SSH server (deprecated in Safeguard v6.13) Boolean Boolean No
Timeout Optional Timeout. If not specified, the default SSH timeout will be used Value Integer No
SoftwareVersionVariableName The name of a variable that will be used to report the remote server’s software name and version, if the remote server provides this information String String No
ReuseConnection If true, then the open connection identified by ConnectionObjectname will be reused. If false, then a new connection will be opened reusing the previous connection parameters Value Boolean No
Command The command to run on this connection Value String Yes
BufferName The name of the variable to contain the output from the command Value String Yes
CommandContainsSecret If true, the command contains sensitive information and should not be logged in the comms log Value Boolean No
OutputContainsSecret If true, the output from the command may contain sensitive information and should not be logged in the commas log Value Boolean No
SuppressExceptions If true, do not throw an exception if the executing command returns stderr data Value Boolean No (default false)

Examples

Example
Run a sequence of 2 commands using the same connection. The connection will be opened when the first command is executed, and the open connection will be reused for the second command.

{
    "Try": {
        "Do": [
            {       
                "ExecuteCommand": {    
                    "ConnectionObjectName": "Global:ConnectSsh",
                    "Port": "%Port%",
                    "NetworkAddress": "%Address%",
                    "Login": "%UserName%",
                    "Password": "%Password::$%",
                    "UserKey": "%LoginKey::$%",
                    "CheckHostKey": "%CheckHostKey%",
                    "Hostkey": "%HostKey::$%",
                    "Timeout": "%Timeout%",
                    "ReuseConnection": false,
               	    "Command": "whoami",
           	    "BufferName": "CmdOutput"
                }
            },
            {
                "Log": {
                    "Text" : "Output from 'whoami' : %CmdOutput%" 
                }
            },
            {
                "ExecuteCommand": {
                    "ConnectionObjectName": "Global:ConnectSsh",
        	    "ReuseConnection": true,
                    "Command": "hostname",
	            "BufferName": "CmdOutput"
                }
            },
            {
                "Log": {
                    "Text" : "Output from 'hostname' : %CmdOutput%" 
                }
            }
            "Catch": [
                { "Throw": { "Value": "ExecuteCommand failed: %Exception%" } }
           ]
      }
 }