SSH Plugin

The plugin provides functionality to execute commands via Secure Shell (SSH) connection protocol.

Installation

Copy the below line to dependencies section of the project build.gradle file

Please make sure to use the same version for all VIVIDUS dependencies.
Example 1. build.gradle
```
implementation('org.vividus:vividus-plugin-ssh')
```
If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

Properties

It’s allowed to configure unlimited number of SSH connections via mechanism of the dynamic properties. The properties prefix example is:

ssh.server.my-server

where my-server is a key used to refer SSH connection in the steps. The key is defined by users, it must be unique and can’t contain dots.

The properties marked with bold are mandatory.

Name Acceptable values Default Description

Name	Acceptable values	Default	Description
`ssh.server.<key>.pseudo-terminal-enabled`	`true` `false`	`false`	Allocate a Pseudo-Terminal
`ssh.server.<key>.username`	<string>		The name of the user logging in
`ssh.server.<key>.host`	hostname or IP		The remote host
`ssh.server.<key>.port`	0..65535		The remote port (The standard TCP port for SSH is 22)
`ssh.server.<key>.agent-forwarding`	`true` `false`	`false`	Enable forwarding of the authentication agent connection
The following properties are used only for the password-based authentication
`ssh.server.<key>.password`	<string>		The password
The following properties are used only for the public key authentication
`ssh.server.<key>.private-key`	<string>		The private key, must not be used along with `private-key-file` property
`ssh.server.<key>.public-key`	<string>		The public key, must not be used along with `public-key-file` property
`ssh.server.<key>.private-key-file`	<string>		The path to a private key file on the filesystem, must not be used along with `private-key` property
`ssh.server.<key>.public-key-file`	<string>		The path to a public key file on the filesystem, must not be used along with `public-key` property
`ssh.server.<key>.passphrase`	<string>		The passphrase for the private key
The following properties are not applicable for SFTP
`ssh.server.<key>.channel-type`	`exec` `shell`	`exec`	In common *nix OpenSSH server: The `shell` channel executes a login shell (as if you login with SSH terminal client). The `exec` command takes a command as an "argument" and executes it in an isolated environment – still via user’s default shell, but not as a "login" shell, what may cause significant differences in the command execution. With less common SSH servers, the difference can be even more significant. Some servers may not even support one of the channels. It is also quite common that they seemingly support both, but one of them (typically the `exec`) is completely broken.

ssh.server.<key>.pseudo-terminal-enabled

true
false

false

Allocate a Pseudo-Terminal

ssh.server.<key>.username

The name of the user logging in

ssh.server.<key>.host

hostname or IP

The remote host

ssh.server.<key>.port

0..65535

The remote port (The standard TCP port for SSH is 22)

ssh.server.<key>.agent-forwarding

true
false

false

Enable forwarding of the authentication agent connection

The following properties are used only for the password-based authentication

ssh.server.<key>.password

The password

The following properties are used only for the public key authentication

ssh.server.<key>.private-key

The private key, must not be used along with private-key-file property

ssh.server.<key>.public-key

The public key, must not be used along with public-key-file property

ssh.server.<key>.private-key-file

The path to a private key file on the filesystem, must not be used along with private-key property

ssh.server.<key>.public-key-file

The path to a public key file on the filesystem, must not be used along with public-key property

ssh.server.<key>.passphrase

The passphrase for the private key

The following properties are not applicable for SFTP

ssh.server.<key>.channel-type

exec
shell

exec

In common *nix OpenSSH server:

The shell channel executes a login shell (as if you login with SSH terminal client).
The exec command takes a command as an "argument" and executes it in an isolated environment – still via user’s default shell, but not as a "login" shell, what may cause significant differences in the command execution.

With less common SSH servers, the difference can be even more significant. Some servers may not even support one of the channels. It is also quite common that they seemingly support both, but one of them (typically the exec) is completely broken.

Steps

Configure dynamic SSH connection

Creates a new dynamic SSH connection from the provided parameters, the connection is available only within the story creating the connection.

When I configure SSH connection with key `$connectionKey` and parameters:$connectionParameters

$connectionKey - The key to assign to the creating SSH connection. In case if the key conflicts with a global connection key, the dynamic connection will take precedence within the story.
$connectionParameters - The ExamplesTable with SSH connection parameters.

The parameters marked with bold are mandatory.

Name Acceptable values Default Description

Name	Acceptable values	Default	Description
`pseudo-terminal-enabled`	`true` `false`	`false`	Allocate a Pseudo-Terminal
`username`	<string>		The name of the user logging in
`host`	hostname or IP		The remote host
`port`	0..65535		The remote port (The standard TCP port for SSH is 22)
`agent-forwarding`	`true` `false`	`false`	Enable forwarding of the authentication agent connection
The following parameters are used only for the password-based authentication
`password`	<string>		The password
The following parameters are used only for the public key authentication
`private-key`	<string>		The private key, must not be used along with `private-key-file` property
`public-key`	<string>		The public key, must not be used along with `public-key-file` property
`private-key-file`	<string>		The path to a private key file on the filesystem, must not be used along with `private-key` property
`public-key-file`	<string>		The path to a public key file on the filesystem, must not be used along with `public-key` property
`passphrase`	<string>		The passphrase for the private key
The following parameters are not applicable for SFTP
`channel-type`	`exec` `shell`	`exec`	In common *nix OpenSSH server: The `shell` channel executes a login shell (as if you login with SSH terminal client). The `exec` command takes a command as an "argument" and executes it in an isolated environment – still via user’s default shell, but not as a "login" shell, what may cause significant differences in the command execution. With less common SSH servers, the difference can be even more significant. Some servers may not even support one of the channels. It is also quite common that they seemingly support both, but one of them (typically the `exec`) is completely broken.

pseudo-terminal-enabled

true
false

false

Allocate a Pseudo-Terminal

username

The name of the user logging in

host

hostname or IP

The remote host

port

0..65535

The remote port (The standard TCP port for SSH is 22)

agent-forwarding

true
false

false

Enable forwarding of the authentication agent connection

The following parameters are used only for the password-based authentication

password

The password

The following parameters are used only for the public key authentication

private-key

The private key, must not be used along with private-key-file property

public-key

The public key, must not be used along with public-key-file property

private-key-file

The path to a private key file on the filesystem, must not be used along with private-key property

public-key-file

The path to a public key file on the filesystem, must not be used along with public-key property

passphrase

The passphrase for the private key

The following parameters are not applicable for SFTP

channel-type

exec
shell

exec

In common *nix OpenSSH server:

The shell channel executes a login shell (as if you login with SSH terminal client).
The exec command takes a command as an "argument" and executes it in an isolated environment – still via user’s default shell, but not as a "login" shell, what may cause significant differences in the command execution.

Example 2. Configure SSH connection dynamically

When I configure SSH connection with key `my-connection` and parameters:
|username |host       |port|password|
|admin    |10.10.10.10|22  |Pa$$w0rd|

Execute commands

Retrieves SSH connection parameters by key, opens SSH session and executes commands remotely via the specified protocol.

When I execute commands `$commands` on $connectionKey over $protocol

$commands - Semicolon-separated commands to execute.
$connectionKey - The SSH connection key matching any of configured ones.

$protocol - The protocol of execution: SSH or SFTP.

Table 1. The list of the supported `SFTP` commands
Command	Description
`cd path`	Change remote directory to `path`
`get remote-path`	Download file
`ls [path]`	Display remote directory listing (optionally directory `path` can be specified)
`mkdir path`	Create remote directory
`pwd`	Display remote working directory
`rmdir path`	Remove remote directory
`rm path`	Remove remote file

Example 3. Execute commands via SSH protocol

When I execute commands `cd /; pwd` on my-host over SSH

Example 4. Execute commands via SFTP protocol

When I execute commands `cd /Users` on my-host over SFTP

Execute commands via SFTP and save the result

Retrieves SSH connection parameters by key, opens SSH session, executes SFTP commands remotely and saves the result of the commands to the variable.

When I execute commands `$commands` on $connectionKey over SFTP and save result to $scopes variable `$variableName`

$commands - Semicolon-separated SFTP commands to execute.
It’s allowed to combine any SFTP commands, but at least one of them should return result. SFTP commands returning results are:

get remote-path

ls [path]

pwd
$connectionKey - The SSH connection key matching any of configured ones.
$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to save the SFTP commands execution result.

Example 5. Retrive file via SFTP protocol

When I execute commands `get remote-file.txt` on my-host over SFTP and save result to scenario variable `file-content`

Create a file via SFTP

Retrieves SSH connection parameters by key, opens SSH session and creates file with the given content at the provided remote destination.

When I create file with content `$content` at path `$destination` on $connectionKey over SFTP

$content - The content of the file to create.
$destination - The remote file destination.
$connectionKey - The SSH connection key matching any of configured ones.

Example 6. Create a file via SFTP

When I create file with content `hello world!` at path `remote-file.txt` on my-host over SFTP

Copy a file via SFTP

Retrieves SSH connection parameters by key, opens SSH session and copies the local file to the remote destination.

When I copy local file located at `$filePath` to path `$destination` on $connectionKey over SFTP

$filePath - The path of the file to copy.
$destination - The remote file destination.
$connectionKey - The SSH connection key matching any of configured ones.

Example 7. Copy a file via SFTP

When I copy local file located at `local-file.txt` to path `remote-file.txt` on my-host over SFTP

Port forwarding

Opens an SSH session and forwards a local port to a remote host and port using the provided parameters. All the opened SSH sessions will be closed after all the batches are executed.

When I forward port through SSH using parameters:$parameters

$parameters - The ExamplesTable with SSH port forwarding and connection parameters.

The parameters marked with bold are mandatory.

Name Acceptable values Default Description

Name	Acceptable values	Default	Description
`local-port`	0..65535		The local TCP port to bind on the client machine. Incoming connections to this port are sent through the SSH tunnel
`remote-port`	0..65535		The TCP port on the `remote-host` that receives the forwarded traffic
`remote-host`	hostname or IP		The target host (reachable from the SSH server) to which the forwarded traffic should be delivered. This can be an internal host not directly accessible from the client :connection-parameters-prefix:
`username`	<string>		The name of the user logging in
`host`	hostname or IP		The remote host
`port`	0..65535		The remote port (The standard TCP port for SSH is 22)
`agent-forwarding`	`true` `false`	`false`	Enable forwarding of the authentication agent connection
The following parameters are used only for the password-based authentication
`password`	<string>		The password
The following parameters are used only for the public key authentication
`private-key`	<string>		The private key, must not be used along with `private-key-file` property
`public-key`	<string>		The public key, must not be used along with `public-key-file` property
`private-key-file`	<string>		The path to a private key file on the filesystem, must not be used along with `private-key` property
`public-key-file`	<string>		The path to a public key file on the filesystem, must not be used along with `public-key` property
`passphrase`	<string>		The passphrase for the private key

local-port

0..65535

The local TCP port to bind on the client machine. Incoming connections to this port are sent through the SSH tunnel

remote-port

0..65535

The TCP port on the remote-host that receives the forwarded traffic

remote-host

hostname or IP

The target host (reachable from the SSH server) to which the forwarded traffic should be delivered. This can be an internal host not directly accessible from the client

:connection-parameters-prefix:

username

The name of the user logging in

host

hostname or IP

The remote host

port

0..65535

The remote port (The standard TCP port for SSH is 22)

agent-forwarding

true
false

false

Enable forwarding of the authentication agent connection

The following parameters are used only for the password-based authentication

password

The password

The following parameters are used only for the public key authentication

private-key

The private key, must not be used along with private-key-file property

public-key

The public key, must not be used along with public-key-file property

private-key-file

The path to a private key file on the filesystem, must not be used along with private-key property

public-key-file

The path to a public key file on the filesystem, must not be used along with public-key property

passphrase

The passphrase for the private key