SSH Slaves plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID ssh-slaves Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
1.10 (archives)
Aug 06, 2015
ssh-credentials (version:1.6.1)
credentials (version:1.9.4)
Source Code
Issue Tracking
Pull Requests
Open Issues
Pull Requests
Stephen Connolly (id: stephenconnolly)
Kohsuke Kawaguchi (id: kohsuke)
Olivier Lamy (id: olamy)
Usage Installations 2014-Nov 96928
2014-Dec 96870
2015-Jan 101205
2015-Feb 102099
2015-Mar 110634
2015-Apr 110070
2015-May 110039
2015-Jun 115861
2015-Jul 119273
2015-Aug 118286
2015-Sep 121872
2015-Oct 124346

SSH Slaves plugin

This plugin allows you to manage slaves running on *nix machines over SSH. It adds a new type of slave launch method. This launch method will

  • Open a SSH connection to the specified host as the specified username.
  • Checks the default version of java for that user.
  • [not implemented yet] If the default version is not compatible with Jenkins's slave.jar, tries to find a version of java that is.
  • Once it has a suitable version of java, copies the latest slave.jar via SFTP.
  • Starts the slave process.

Integration with SSH Credentials Plugin

As of version 0.23 this plugin is now integrated with the SSH Credentials Plugin. This changes how slaves are configured. The Node configuration is simplified, e.g. you now just have a Credentials drop down listing all the "Global" and "System" scoped credentials.

If you are upgrading from a previous version, the plugin should try to inject any required SSH credentials in the Credentials Plugin using the credentials that were previously stored in each node's definition.

To define credentials to use when connecting slaves you need to go to the Jenkins » Manage Jenkins » Manage Credentials screen
Once on this screen you can add SSH credentials, either using a Username & Password or using a Username & Private Key
Credential scope controls where the credentials can be used:

  • System scope is only available for the root Jenkins instance (in other words Jenkins can use it to connect build nodes, but the credentials are not available to build jobs)
  • Global scope is available for the root Jenkins instance and any child items (in other words Jenkins can use it to connect build nodes, build jobs can use it for other SSH Credentials enabled plugins) 

When you have a lot of different credentials it can be useful to put those credentials into credential domains, e.g.

The drop-down for selecting credentials will construct a specification that includes the URI Scheme of ssh and the specified hostname and port, so where you have created the appropriate credential domains the choice of credentials will be restricted to those outside of any credential domain and those from matching credential domains. This can help differentiate between multiple keys/password associated with the same username.

Common Pitfalls

Login profile files

When the SSH slaves plugin connects to a slave, it does not run an interactive shell. Instead it does the equivalent of your running "ssh slavehost command..." a few times, eventually to run "ssh slavehost java -jar ...". Exactly what happens on the slave as a result of this depends on the SSHD implementation, but OpenSSH runs this with "bash -c command ..." (or whatever your login shell is.)

This means some of your login profiles that set up your environment is not read by your shell. See this post for more details.

If you need to set additional environment variables for slave, consider using EnvInject Plugin or write a wrapper script around java and specify that in the JavaPath field.

If your login shell does not understand the command syntax used (e.g. the fish shell), use the advanced options Prefix Start Slave Command and Suffix Start Slave Command to wrap the slave command in e.g. sh -c " and ".


See SSH slaves and Cygwin for the discussion of how to use this plugin to talk to Cygwin SSHD server.

Version History

Version 1.10 (Aug 06, 2015)

  • Update JDK version for auto installer
  • Timeout the afterDisconnect cleanup thread to prevent deadlock JENKINS-23560

Version 1.9 (Nov 04, 2014)

  • Diagnosability improvements in case of a connection loss. See Remoting issue.

Version 1.8 (Oct 07, 2014)

  • SECURITY-158 fix.
  • German localization updated.

Version 1.7.1 (Sep 29, 2014)

  • Fix NPE when trying to launch non-reconfigured slaves after upgrade to 1.7 version of plugin.

Version 1.7 (Sep 26, 2014)

  • Protect against some cases where there is no private key resulting in an NPE (possible fix for JENKINS-20332)
  • Updated help text
  • Localization cleanup
  • Improved error diagnostics
  • Allow connection retries (Pull Request #19)
  • Enforce timeout for connection cleanup (possible fix for JENKINS-14332)

Version 1.6 (Feb 5, 2014)

  • Add initial connection timeout to prevent stalled connections from preventing slave connection.
  • Update credentials plugin to 1.9.4 and ssh-credentials to 1.6.1 to ensure the in-place addition of credentials is available.
  • Change the hard-coded JDK from 1.6.0_16 to 1.6.0_45

Version 1.5 (Oct 16, 2013)

  • Fix to how credentials are sourced for the drop-down list
  • Use credentials plugin's <c:select/> so that when credentials plugin adds the ability for in-place credential addition this can be picked up without modifying ssh-slaves

Version 1.4 (Oct 8, 2013)

Version 1.3 (Oct 4, 2013)

  • Reworked the upgrading of credentials logic. Should be much improved and result in a true minimal initial set

Version 1.2 (Aug 8, 2013)

  • Fixed binary compatibility for plugins depending on this one.

Version 1.1 (Aug 7, 2013)

  • Forced upgrade of dependency SSH Credentials.

Version 1.0 (Aug 7, 2013)

  • Upgrade dependencies to SSH Credentials Plugin 1.0 and Credentials Plugin 1.6 and migrated code from legacy data type to the new StandardCredential based types.
  • NOTE: It will not be possible to downgrade to previous releases without risking the loss of some configuration data.

Version 0.27 (Jun 21, 2013)

  • Reduce the # of threads spawned. Even more so with Jenkins 1.521 and onward.

Version 0.25 (Apr 17, 2013)

  • When upgrading credentials from pre 0.23 format, ensure that the credentials are persisted with the correct security context for persisting system/global credentials (issue #17648)

Version 0.24 (Apr 16, 2013)

  • Removed some unnecessary debug code that remained as a fragment during development of the bulk data transfer improvements in 0.23
  • Added some Japanese localizations
  • Prevented persistence of duplicate credentials under some code paths
  • Restored support for empty username as indicator of the user that Jenkins is running as.
  • Upgrade to latest version of te ssh-credentials plugin. 

Version 0.23 (Mar 21, 2013)

  • Rely on SSH Credentials Plugin for unified credential handling across different places that use SSH
  • Performance improvement on bulk data transfer when used in a large latency/high bandwidth network (JENKINS-7813)

Version 0.22 (Dec 07, 2012)

  • Find slave.jar even when running from hudson-dev:run.
  • Allow environment variables to be declared in the java path, that are then expanded according to environment variables declared on the node or globally.

Version 0.21 (Oct 26, 2011)

  • Slave is slow copying maven artifacts to master (JENKINS-3922).

Version 0.20 (Sep 28, 2011)

  • JDK installation on SSH slaves with newer Jenkins was broken (JENKINS-10641)

Version 0.19 (Aug 25, 2011)

  • Fixed possible NPE during error recovery
  • Improved the error message when the server doesn't support the configured authentication mode (JENKINS-6714)

Version 0.18 (Jul 06, 2011)

  • Ability to programmatically control the JDK to be installed

Version 0.17 (Jun 13, 2011)

  • Fixed an API incompatibility regression introduced in 0.15.

Version 0.16 (Apr 28, 2011)

  • Improved error diagnostics for unreadable SSH private key file.

Version 0.15 (Mar 26, 2011)

  • New field to be able to configure the java command to use to start the slave

Version 0.14 (Nov 2, 2010)

  • Delete file via ssh if SFTP is not available (JENKINS-7006)

Version 0.13 (Aug 13, 2010)

  • Added Japanese localization.
  • Fixed deprecated api.

Version 0.12 (June 1, 2010)

  • Avoid "password argument is null" error (JENKINS-6620)
  • Version check of JDKs was broken in locales that don't use '.' as the floating point separator (JENKINS-6441)
  • If SFTP is not available on the slave, use SCP (JENKINS-6239)
  • Hudson fails to detect JVM versions when loading older data (JENKINS-4856)

Version 0.10 (May 2, 2010)

  • Launcher was storing password in plaintext (JENKINS-5363)
  • Check node properties for JAVA_HOME and JDK tool path when locating java (JENKINS-5412)
  • Support for openjdk 7 (JENKINS-6005)

Version 0.9 (December 9, 2009)

  • JDK auto installation works on Windows+MKS environment (report)

Version 0.8 (October 23, 2009)

  • Allow OpenJDK in Java discovery (report)
  • Added a fool-proof check to detect a garbage in SSH exec session to avoid SFTP packet length problem (report)

Version 0.7 (July 27, 2009)

  • Supports private keys in the PuTTY format.
  • Fixed possible NPE (report)

Version 0.6 (July 20, 2009)

  • Improved the error reporting if the plugin fails to find usable Java implementation (report)
  • User name can be now omitted, which defaults to the user that's running the Hudson master.

Version 0.5 (April 28, 2009)

  • Added support for specifying the Slave JVM options

Version 0.4 (February 2, 2009)

  • Unknown

Version 0.3 (January 30, 2009)

  • Unknown

Version 0.2 (June 14, 2008)

  • Tidy-ups and i18n enabling the plugin

Version 0.1 (June 9, 2008)

  • Initial release


plugin-slaves plugin-slaves Delete
credentials-consumer credentials-consumer Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment