SSH Task

Properties   Config Settings  

The SSH Component enables your SSIS Package to execute remote commands over SSH.

Remarks

The SSH Task uses the SSH "exec" subsystem to remotely execute commands from your SSIS Package.

SSH Send Task

The SSH Send Task provides an ultra light-weight remote command execution client for your SSIS Package. You must first set an SSHHost. If the SSH server requires authentication, you should set the necessary SSHUser, and either SSHPassword or SSHCert depending on the SSHAuthMode you wish to use. Once the SSH server information is set, you must enter the Command you wish to execute.

Whenever called from the SSIS Package, the task will execute the given command. If the Stdin property has any data, that data will supplied to the executing command's standard input.

Once the command has finished executing, the task will write the output from the command's standard out pipe to the variable pointed to by the CommandStdOut property. It will also write the command's exit code to the variable pointed to by the CommandExitStatus property, and any data from the standard err pipe to the variable pointed to by the CommandErrorMessage property.

Sender Property List

---

The following is the full list of the properties of the sender task with short descriptions. Click on the links for further details.

Command	The command to be sent to the remote host.
CommandErrorMessage	The error message, if any, returned by the server after command execution.
CommandExitStatus	The exit code for the executed command for the current message.
CommandStdErr	The standard error output of the executed Command .
CommandStdOut	The standard output of the executed Command .
FailOnError	Controls how the component treats error codes returned by command execution.
Firewall	A set of properties related to firewall access.
LogFile	The file to write logging information to at runtime.
LogMode	What information gets logged during component execution.
Other	Defines a set of configuration settings to be used by the component.
PersistentConnection	Instructs the component whether to keep the connection to the server open.
RuntimeLicense	Specifies the component runtime license key.
SSHAcceptServerHostKey	Instructs the component to accept the server host key that matches the supplied key.
SSHAcceptServerHostKeyAcceptAny	Tells the component to accept any server certificate.
SSHAuthMode	The type of authentication used by the component.
SSHCert	The certificate to use for client authentication during the SSH handshake.
SSHCompressionAlgorithms	A comma-separated list of compression algorithms allowed for this connection.
SSHHost	The address of the SSH host.
SSHPassword	The password for SSH password-based authentication.
SSHPort	The port on the SSH server where the SSH service is running; by default, 22.
SSHUser	The username for SSH authentication.
Stdin	A string of data that will be supplied to the executing command's standard input.
Timeout	A timeout for the component.

Config Settings

---

The following is a list of config settings for the task with short descriptions. Click on the links for further details.

KeyRenegotiationThreshold	Sets the threshold for the SSH Key Renegotiation.
Logoff	Whether or not to logoff from the server after execution.
LogSSHPackets	If True, detailed SSH packet logging is performed.
SSHAcceptServerHostKeyFingerPrint	Instructs the component to accept the server's host key with this fingerprint.
SSHEncryptionAlgorithms	A comma-separated list containing all allowable compression algorithms.
SSHKeyExchangeAlgorithms	Specifies the supported key exchange algorithms.
SSHMacAlgorithms	Specifies the supported Mac algorithms.
SSHPublicKeyAlgorithms	Specifies the supported public key algorithms for the server's public key.
UseStrictKeyExchange	Specifies how strict key exchange is supported.
AbsoluteTimeout	Determines whether timeouts are inactivity timeouts or absolute timeouts.
LocalHost	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
TcpNoDelay	Whether or not to delay when sending packets.
UseInternalSecurityAPI	Tells the component whether or not to use the system security libraries or an internal implementation.

Command Property (SSH Task)

The command to be sent to the remote host.

Data Type

String

Default Value

""

Remarks

Assigning a UNIX command to this property makes the task attempt to connect to the SSHHost and execute the command under the user's default shell. There is no need to append an end-of-line character to the command. All output from the remote application will be returned to the task.

Note: the task will terminate the connection once the remote application has finished executing.

CommandErrorMessage Property (SSH Task)

The error message, if any, returned by the server after command execution.

Data Type

String

Default Value

""

Remarks

After executing the Command, the server will send a notification containing the CommandExitStatus. The server may also send a textual representation of that code, which will be stored in CommandErrorMessage.

This property is not available in the Receiver.

CommandExitStatus Property (SSH Task)

The exit code for the executed command for the current message.

Data Type

Integer

Default Value

0

Remarks

After executing the Command, the server will send a notification containing the CommandExitStatus. The server may also send a textual representation of that code, which will be stored in CommandErrorMessage.

This property is not available in the Receiver.

CommandStdErr Property (SSH Task)

The standard error output of the executed Command .

Data Type

String

Default Value

""

Remarks

This property will contain the standard error output of the Command once execution has completed.

This property is not available in the Receiver.

CommandStdOut Property (SSH Task)

The standard output of the executed Command .

Data Type

String

Default Value

""

Remarks

This property will contain the standard output of the Command once execution has completed.

This property is not available in the Receiver.

FailOnError Property (SSH Task)

Controls how the component treats error codes returned by command execution.

Data Type

Boolean

Default Value

true

Remarks

If set to True, FailOnError will cause the task to stop processing the inbound data and raise an error if the SSHHost returns an unsuccessful error code when executing the Command.

If set to False, the task will return all error information through the CommandExitStatus and CommandErrorMessage. Any standard output from the command's execution will be stored as usual in the message body.

Note: since FailOnError defaults to True, some improper command values may result in unexpected errors. In this case, it is useful to examine the standard output for any hints on proper command usage by setting FailOnError to false and writing the contents of the message to a file.

Firewall Property (SSH Task)

A set of properties related to firewall access.

Data Type

Firewall

Remarks

This is a Firewall type property which contains fields describing the firewall through which the task will attempt to connect.

LogFile Property (SSH Task)

The file to write logging information to at runtime.

Data Type

String

Default Value

""

Remarks

To write logging information to a file instead of using the task's logging API, set this property to a valid file on disk.

When set, any logging information is appended to the specified file and not written to the task's logging API.

LogMode Property (SSH Task)

What information gets logged during component execution.

Data Type

Enumeration

Possible Values

Verbose (0)
Info (1)
Warning (2)
Error (3)
Fatal (4)

Default Value

3

Remarks

This property controls what information the task logs. The possible values have the following affect on the task's behavior:

Other Property (SSH Task)

Defines a set of configuration settings to be used by the component.

Data Type

String

Default Value

""

Remarks

The task accepts one or more configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the task, access to these internal properties is provided through the Other property.

The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line. For example: configname1=value1 configname2=value2

PersistentConnection Property (SSH Task)

Instructs the component whether to keep the connection to the server open.

Data Type

Boolean

Default Value

false

Remarks

If set to true, the task will first attempt to use an existing connection. If no such connection exists, it will create a new connection. When the task completes, it will persist the connection so that the task will reuse it during the next polling interval. Setting this property to true can improve performance if you are polling very frequently.

Set the Logoff configuration to tell the task to logoff from the persisted connection after completion.

RuntimeLicense Property (SSH Task)

Specifies the component runtime license key.

Data Type

String

Default Value

""

Remarks

You can use the RuntimeLicense property to set the runtime key for the task license.

SSHAcceptServerHostKey Property (SSH Task)

Instructs the component to accept the server host key that matches the supplied key.

Data Type

Certificate

Remarks

If the host key that will be used by the server is known in advance, this property may be set to accept the expected key. If you are using the fingerprint, you may supply it to the SSHAcceptServerHostKeyFingerPrint setting by HEX encoding the values in the form "0a:1b:2c:3d". If this property is not set the server will not be authenticated, and the connection will be refused by the client.

Note: You may also set SSHAcceptServerHostKeyAcceptAny to True without opening the certificate selection dialog to force the adapter to unilaterally authenticate any server during the security handshake. It is strongly recommended that you use this only for testing purposes.

SSHAcceptServerHostKeyAcceptAny Property (SSH Task)

Tells the component to accept any server certificate.

Data Type

Boolean

Default Value

false

Remarks

When set to true, the task will unilaterally authenticate any server during the security handshake. It is strongly recommended that you use this only for testing purposes.

SSHAuthMode Property (SSH Task)

The type of authentication used by the component.

Data Type

Enumeration

Possible Values

None (0)
Multi Factor (1)
Password (2)
Public Key (3)
Keyboard Interactive (4)
GSSAPIWith Mic (5)

Default Value

2

Remarks

SSHAuthMode controls how the task attempts to authenticate when connecting to the SSHHost. The following authentication methods are available:

SSHCert Property (SSH Task)

The certificate to use for client authentication during the SSH handshake.

Data Type

Certificate

Remarks

This property is used to assign a specific certificate for SSH client authentication.

This field is used to set a Private Key Certificate.

Private key certificates may be loaded from the registry, from files in PKCS#12 format, or from a PEM file format. If you click on the ellipses, a certificate selection dialog will open. To select a private key from the system registry, select the System Store tab or the User Store tab, and highlight the appropriate registry store. The list of certificates which have private keys will be shown below.

To select a private key certificate from a file in PKCS#12 format, select the PFX Store tab. The browse button can be used to examine the file system for PKCS#12 (.pfx or .p12) certificates. If you wish to examine the certificate, provide the password in the field provided and click on the Open button to examine the file store for certificates present. To load a certificate from PEM files, select the PEM tab. Like the PFX file selection, you can specify the password and click the Open button to examine the certificates in the PEM store, or you may paste any PEM data stored in memory.

Regardless of how you selected the certificate, once you hit the OK button, the task will attempt to verify that certificate selection. If successful, the subject of the certificate will be displayed in the property field. If the task was not able to verify the selection, a dialog box will appear instead detailing the verification error.

SSHCompressionAlgorithms Property (SSH Task)

A comma-separated list of compression algorithms allowed for this connection.

Data Type

String

Default Value

"none"

Remarks

This list is used for both directions: client to server and server to client. When negotiating algorithms, each side sends a list of all algorithms it supports or allows. The algorithm chosen for each direction is the first algorithm to appear in the sender's list that the receiver supports, so it is important to list multiple algorithms in preferential order. If no algorithm can be agreed upon, the task will raise an error and the connection will be aborted.

SSHCompressionAlgorithms must be set to a comma-separated list containing at least one of the following values:

SSHHost Property (SSH Task)

The address of the SSH host.

Data Type

String

Default Value

""

Remarks

The SSHHost property specifies the IP address (IP number in dotted internet format) or Domain Name of the remote host. It is set before a connection is attempted and cannot be changed once a connection is established.

If the SSHHost property is set to a Domain Name, a DNS request is initiated, and upon successful termination of the request, the SSHHost property is set to the corresponding address. If the search is not successful, an error is logged.

SSHPassword Property (SSH Task)

The password for SSH password-based authentication.

Data Type

Password

Default Value

""

Remarks

SSHPassword specifies the password which is used to authenticate the client to the SSH server.

SSHPort Property (SSH Task)

The port on the SSH server where the SSH service is running; by default, 22.

Data Type

Integer

Default Value

22

Remarks

The SSHPort specifies a service port on the SSH host to connect to.

SSHUser Property (SSH Task)

The username for SSH authentication.

Data Type

String

Default Value

""

Remarks

SSHUser specifies the username which is used to authenticate the client to the SSH server. This property is required.

Stdin Property (SSH Task)

A string of data that will be supplied to the executing command's standard input.

Data Type

String

Default Value

""

Remarks

During execution of the Command property, if the Stdin property has any data, that data will supplied to the executing command's standard input.

This property is write-only and not available at design time.

This property is not available in the Receiver.

Timeout Property (SSH Task)

A timeout for the component.

Data Type

Integer

Default Value

60

Remarks

If the Timeout property is set to 0, all operations will run uninterrupted until successful completion, or an error condition is encountered.

If Timeout is set to a positive value, the task will wait for the operation to complete before returning control.

If Timeout expires, and the operation is not yet complete, the task fails with an error.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behavior of the task may be changed to absolute timeouts, i.e. the task will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by the AbsoluteTimeout configuration setting.

The default value for the Timeout property is 60 (seconds).

Certificate Type

The digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Firewall Type

The firewall the component will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall such as the firewall Host and the FirewallType.

Fields

Config Settings (SSH Task)

The task accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the task, access to these internal properties is provided through the Other property.

SSH Config Settings

General Config Settings