Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jenkinsci/ssh-steps-plugin

Jenkins pipeline steps which provides SSH facilities such as command execution or file transfer for continuous delivery.
https://github.com/jenkinsci/ssh-steps-plugin

jenkins jenkins-pipeline pipeline pipeline-step remote-shell ssh steps

Last synced: about 1 month ago
JSON representation

Jenkins pipeline steps which provides SSH facilities such as command execution or file transfer for continuous delivery.

Awesome Lists containing this project

README 

        
= SSH Pipeline Steps

:toc: macro

:note-caption: :information_source:

:tip-caption: :bulb:



image::docs/static/images/JenkinsPlusSSH.png[Jenkins,300]



link:https://ci.jenkins.io/job/Plugins/job/ssh-steps-plugin/job/master/[image:https://ci.jenkins.io/job/Plugins/job/ssh-steps-plugin/job/master/badge/icon[Build]] image:https://img.shields.io/badge/License-Apache%202.0-blue.svg[License] link:https://plugins.jenkins.io/ssh-steps[image:https://img.shields.io/badge/SSH%20Steps-WIKI-blue.svg[Wiki]] image:https://badges.gitter.im/jenkinsci/ssh-steps-plugin.svg[link="https://gitter.im/jenkinsci/ssh-steps-plugin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]



Jenkins pipeline steps which provides SSH facilities such as command execution or file transfer for continuous delivery. It internally uses the library of https://github.com/int128/groovy-ssh[Groovy SSH].



Read more about the YAML extension of this plugin at https://engineering.cerner.com/blog/ssh-steps-for-jenkins-pipeline/[this blog post]



'''

toc::[]



== 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.



[%header,cols=3*]

|===

|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

a|Defaults to *SEVERE*



Possible values, refer to java logging https://docs.oracle.com/javase/7/docs/api/java/util/logging/Level.html[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



[%header,cols=3*]

|===

|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



[%header,cols=3*]

|===

|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



```groovy

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



[%header,cols=3*]

|===

|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



```groovy

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



[%header,cols=3*]

|===

|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



```groovy

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



[%header,cols=3*]

|===

|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



```groovy

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



[%header,cols=3*]

|===

|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



```groovy

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.

```groovy

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:

image::docs/static/images/ExampleWithCredentials.png[ExampleWithCredentials,900]



==== Blue Ocean View:

image::docs/static/images/ExampleWithCredentialsBlueOcean.png[ExampleWithCredentialsBlueOcean,900]



== link:CONTRIBUTING.adoc[Contributing Guide]



== link:CHANGELOG.adoc[Changelog]



== Maintainers



* https://github.com/nrayapati[Naresh Rayapati]

* https://github.com/ghenkes[Gabe Henkes]

* https://github.com/wwftw[Wuchen Wang]



== Disclaimer



Please don't hesitate to log a http://issues.jenkins-ci.org/[JIRA] or github pull request if you need any help or if you can be of help with this plugin :).

Refer to the link:./CONTRIBUTING.adoc[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.

-------