SSH Plugin

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

Installation

Example 1. build.gradle
implementation(group: 'org.vividus', name: 'vividus-plugin-ssh', version: '0.5.0')

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

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

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

true
false

false

Allocate a Pseudo-Terminal

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

ssh.server.<key>.public-key

<string>

The public key

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.

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

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

pseudo-terminal-enabled

true
false

false

Allocate a Pseudo-Terminal

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

public-key

<string>

The public key

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.

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 commands to execute.

  • $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