SSH Pipeline Steps

Jenkins pipeline steps which provides SSH facilities such as command execution or file transfer for continuous delivery. It internally uses the library of Groovy SSH.

Read more about the YAML extension of this plugin at this blog post

Table of Contents

Configuration
- Remote
- Proxy
Pipeline Steps
- sshCommand
- sshScript
- sshPut
- sshGet
- sshRemove
Examples
- withCredentials
Contributing Guide
Changelog
Maintainers
Disclaimer
License

Configuration

Remote

Most of the steps in this plugin require a common step variable called remote, which is Map of remote node settings such as user name, password and so on. Here is list of all possible keys that can be set.

Key	Type	Description
name	String, Mandatory	Remote name, usually this is same as host name.
host	String, Mandatory	Hostname or IP address of the remote host.
port	int	Port. Defaults to port `22`.
user	String, Mandatory	User name.
allowAnyHosts	boolean	If this is `true`, knownHosts is optional. Defaults to `false`.
knownHosts	String, Mandatory	Known hosts file for host key checking.
password	String, one of password, identity or identityFile is required	Password for password authentication.
identity	String, one of password, identity or identityFile is required	Private key for public-key authentication.
identityFile	String, one of password, identity or identityFile is required	Private key file name for public-key authentication.
passphrase	String	Pass-phrase for the private key.
agent	boolean	If this is `true`, Putty Agent or ssh-agent is used on authentication. Defaults to `false`.
timeoutSec	int	Connection timeout and socket read timeout. Defaults to 0 (OS default).
retryCount	int	Retry count to establish connection. Defaults to 0 (no retry).
retryWaitSec	int	Interval time between each retries. Defaults to 0 (immediately).
keepAliveSec	int	Interval time of keep alive messages sent to the remote host. Defaults to 60 seconds.
agentForwarding	boolean	If this is `true`, the agent forwarding is requested on the command execution. Defaults to false.
fileTransfer	String	File transfer method, that is `sftp` or `scp`. Defaults to `sftp`.
encoding	String	Encoding of input and output on the command or shell execution. Defaults to `UTF-8`.
proxy	Proxy, refer below.	If this is set, the proxy server is used to reach the remote host. Defaults to no proxy.
gateway	Remote	Gateway remote host. If this is set, the port-forwarding tunnel is used to reach the remote host. Defaults to no gateway.
appendName	boolean	If this is `true`, `name` is prefixed to each line in the log output. New format: `name\|log`.
logLevel	String	Defaults to SEVERE Possible values, refer to java logging levels SEVERE (highest value) WARNING INFO CONFIG FINE FINER FINEST (lowest value)
pty	boolean	If this is true, a PTY (pseudo-terminal) is allocated on the command execution. Defaults to `false`.

Proxy

Key	Type	Description
name	String, Mandatory	Proxy name
host	String, Mandatory	Hostname or IP address of the proxy server.
port	int, Mandatory	Port of the proxy server.
type	String, Mandatory	Type of the proxy server: `SOCKS` or `HTTP`.
user	String	User name of the proxy server.
password	String	Password of the proxy server.
socksVersion	int	Protocol version when using `SOCKS`: 4 or 5. Defaults to 5.

Pipeline Steps

The following pipeline steps are available with the initial version of this plugin.

sshCommand

This step executes given command on remote node and responds with output.

Input

Key	Type	Description
remote	Remote, Mandatory, Refer to the Remote config for more details.	Host config to run the command on.
command	String, Mandatory	Shell command to run. Appending sudo is optional when `sudo` is `true`.
sudo	boolean, default: `false`.	Interactively supplies the password, not required for password less sudo commands. sshCommand with sudo:true param also requires pty:true on remote config with this upgrade. (This is only applicable for few platforms like Linux so apply this accordingly.)
failOnError	boolean, default: `true`.	If this is `false`, no job failure would occur though there is an error while running the command.
dryRun	boolean, default: `false`	If this is true, no actual connection or operation is performed.

Example

node {
  def remote = [:]
  remote.name = 'test'
  remote.host = 'test.domain.com'
  remote.user = 'root'
  remote.password = 'password'
  remote.allowAnyHosts = true
  stage('Remote SSH') {
    sshCommand remote: remote, command: "ls -lrt"
    sshCommand remote: remote, command: "for i in {1..5}; do echo -n \"Loop \$i \"; date ; sleep 1; done"
  }
}

sshScript

This step executes given script(file) on remote node and responds with output.

Input

Key	Type	Description
remote	Remote, Mandatory, Refer to the Remote config for more details.	Host config to run the command on.
script	String, Mandatory	Script file name from the workspace, current this doesn’t support script with arguments. For that option you would need to copy over the file to remote node and run it as a command.
failOnError	boolean, default: `true`.	If this is `false`, no job failure would occur though there is an error while running the command.
dryRun	boolean, default: `false`	If this is true, no actual connection or operation is performed.

Example

node {
  def remote = [:]
  remote.name = 'test'
  remote.host = 'test.domain.com'
  remote.user = 'root'
  remote.password = 'password'
  remote.allowAnyHosts = true
  stage('Remote SSH') {
    writeFile file: 'abc.sh', text: 'ls -lrt'
    sshScript remote: remote, script: "abc.sh"
  }
}

sshPut

Put a file or directory into the remote host.

Input

Key	Type	Description
remote	Remote, Mandatory, Refer to the Remote config for more details.	Host config to run the command on.
from	String, Mandatory	file or directory path from the workspace.
into	String, Mandatory	file or directory path on the remote node.
filterBy	String, Optional, Defaults to `name`.	Put files by a file filter. Possible values are params on the java File object.
filterRegex	String, Optional.	Put files by a file regex (Groovy syntax). Example: /\.xml$/ - Puts all xml files.
failOnError	boolean, default: `true`.	If this is `false`, no job failure would occur though there is an error while running the command.
dryRun	boolean, default: `false`	If this is true, no actual connection or operation is performed.

Example

node {
  def remote = [:]
  remote.name = 'test'
  remote.host = 'test.domain.com'
  remote.user = 'root'
  remote.password = 'password'
  remote.allowAnyHosts = true
  stage('Remote SSH') {
    writeFile file: 'abc.sh', text: 'ls -lrt'
    sshPut remote: remote, from: 'abc.sh', into: '.'
  }
}

sshGet

Get a file or directory from the remote host.

Input

Key	Type	Description
remote	Remote, Mandatory, Refer to the Remote config for more details.	Host config to run the command on.
from	String, Mandatory	file or directory path from the remote node.
into	String, Mandatory	file or directory path on current workspace.
filterBy	String, Optional, Defaults to `name`.	Get files by a file filter. Possible values are params on the java File object.
filterRegex	String, Optional.	Get files by a file regex (Groovy syntax). Example: /\.xml$/ - Gets all xml files.
failOnError	boolean, default: `true`.	If this is `false`, no job failure would occur though there is an error while running the command.
dryRun	boolean, default: `false`	If this is true, no actual connection or operation is performed.

Example

node {
  def remote = [:]
  remote.name = 'test'
  remote.host = 'test.domain.com'
  remote.fileTransfer = 'scp'
  remote.user = 'root'
  remote.password = 'password'
  remote.allowAnyHosts = true
  stage('Remote SSH') {
    sshGet remote: remote, from: 'abc.sh', into: 'abc_get.sh', override: true
  }
  stage('Retrieve files with regex') {
    def regexPattern = ".+\\.(log|csv)\$"
    sshGet remote: remote, from: '/home/jenkins/', filterRegex: regexPattern, into: 'tests/', override: true
  }
}

sshRemove

Remove a file or directory on the remote host.

Input

Key	Type	Description
remote	Remote, Mandatory, Refer to the Remote config for more details.	Host config to run the command on.
path	String, Mandatory	file or directory path on the remote node
failOnError	boolean, default: `true`.	If this is `false`, no job failure would occur though there is an error while running the command.
dryRun	boolean, default: `false`	If this is true, no actual connection or operation is performed.

Example

node {
  def remote = [:]
  remote.name = 'test'
  remote.host = 'test.domain.com'
  remote.user = 'root'
  remote.password = 'password'
  remote.allowAnyHosts = true
  stage('Remote SSH') {
    sshRemove remote: remote, path: "abc.sh"
  }
}

Examples

withCredentials

An example how these steps can leverage withCredentials to read private key from Jenkins credentials store.

def remote = [:]
remote.name = "node-1"
remote.host = "10.000.000.153"
remote.allowAnyHosts = true

node {
    withCredentials([sshUserPrivateKey(credentialsId: 'sshUser', keyFileVariable: 'identity', passphraseVariable: '', usernameVariable: 'userName')]) {
        remote.user = userName
        remote.identityFile = identity
        stage("SSH Steps Rocks!") {
            writeFile file: 'abc.sh', text: 'ls'
            sshCommand remote: remote, command: 'for i in {1..5}; do echo -n \"Loop \$i \"; date ; sleep 1; done'
            sshPut remote: remote, from: 'abc.sh', into: '.'
            sshGet remote: remote, from: 'abc.sh', into: 'bac.sh', override: true
            sshScript remote: remote, script: 'abc.sh'
            sshRemove remote: remote, path: 'abc.sh'
        }
    }
}

Classic View:

Blue Ocean View:

Contributing Guide

Changelog

Maintainers

Disclaimer

Please don’t hesitate to log a JIRA or github pull request if you need any help or if you can be of help with this plugin :). Refer to the contribution guide for more information.

License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the
License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
“AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
 language governing permissions and limitations under the License.

jenkinsci/ssh-steps-plugin

SSH Pipeline Steps

Configuration

Remote

Proxy

Pipeline Steps

sshCommand

Input

Example

sshScript

Input

Example

sshPut

Input

Example

sshGet

Input

Example

sshRemove

Input

Example

Examples

withCredentials

Classic View:

Blue Ocean View:

Contributing Guide

Changelog

Maintainers

Disclaimer

License