Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 87 Next »

Plugin Information

View SSH Build Agents on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

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 (falling back to scp if SFTP is not available)
  • 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 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 ".

Example: For loading ~/.bash_profile on macOS Slaves set Prefix Start Slave Command to "source ~/.bash_profile && " (intended whitespace at the end).
Make sure to reconnect the slave after changing the slaves commands.

Overall recommendations:


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

Version History

Version 1.26 (Feb 26, 2018)

  • (info) JENKINS-49607 - Report the required Java version when the plugin cannot find Java on the agent
  • (info) JENKINS-43786 - Adapt the adminisitrative monitor to new design in Jenkins 2.103+
  • (info) PR #82 - Do not lookup for credentials in SSHLauncher constructor so that the launcher can be initialized before the Credentials store is fully loaded (for Configuration-as-Code plugin)

Version 1.25.1 (Jan 26, 2018)

  • (error) JENKINS-49032 - Revert usage of "exec" command so that SSH Slaves can connect to Windows agents (regression in 1.25)

Version 1.25 (Jan 05, 2018)

  • (info) JENKINS-48616 - Pass connection timeouts to socket connection logic if launch timeout is defined in agent settings
  • (info) Replace sh with java rather than launching a new process (reverted in 1.25.1)

Version 1.24 (Dec 18, 2017)

  • (error) JENKINS-48613 - Extend the original fix of JENKINS-19465 to prevent the afterDisconnect() handler thread explosion when the SSH connection is locked by the read operation
  • (error) JENKINS-48538 - Prevent NPE in SSHLauncher#isRecoverable() when the exception has empty message
  • (info) JENKINS-48260 - Upgrade the Parent POM to 3.0 and fix Java compatibility tests

Version 1.23 (Dec 12, 2017)

  • (error) JENKINS-44893 - Prevent the "java.lang.ClassNotFoundException: hudson.plugins.sshslaves.verifiers.JenkinsTrilead9VersionSupport" error in logs
  • (error) JENKINS-19465 - Prevent agent hanging and piling up of afterDisconnect() handler threads when the agent gets disconnected before the launch completion
  • (info) PR #73 - Add explicit MIT license definition to the pom.xml file

Version 1.22 (Oct 16, 2017)

  • (error) JENKINS-47448 - Workaround the issue with default JDKInstaller in the plugin by installing Java jdk-8u144
  • (plus) PR #71 - Add Chinese translation

Version 1.21 (Aug 18, 2017)

  • JENKINS-29412 - Minimal required Java Level is determined dynamically. Java 8 is required on agents when Jenkins version is 2.54+
  • JENKINS-38832 - Add support for credential usage tracking
  • PR #58 - Remove obsolete reflection code in SSHLauncher
  • PR #53PR #56, PR #57 - Cleanup typos in the documentation and logs
  • PR #64 - The plugin codebase is now explicitly licensed with MIT License 

Version 1.20 (Jun 13, 2017)

  • JENKINS-44832 IllegalArgumentException under some conditions after update to 1.18 (or 1.19).

Version 1.19 (Jun 12, 2017)

  • JENKINS-44830 NullPointerException after upgrading to 1.18 with slaves configured in 1.14- without a host key verification strategy set since then.

Version 1.18 (Jun 12, 2017)

Version 1.17 (Apr 12, 2017)

  • issue@43481 Updated JRE version which gets automatically installed to 8u121, allowing this mode to work with Jenkins 2.54+ which no longer runs on Java 7.

Version 1.16 (Mar 23, 2017)

  • JENKINS-42969 New Manually trusted key Verification Strategy option introduced in 1.15 did not work in Jenkins 2.30+.

Version 1.15 (Mar 20, 2017)

  • SECURITY-161 (advisory) Host key verification was not performed.
  • JENKINS-42022 Remove 'unix machines' from description.

Version 1.14 (Mar 16, 2017)

Version 1.13 (Jan 28, 2017)

  • PR #41 Do not swallow IOException in case it is not recoverable.
  • JENKINS-40001 Added plugin's description.

Version 1.12 (Dec 01, 2016)

  • JENKINS-40092 slave.jar copy via SCP (fallback when SFTP is unavailable or broken) failed starting with Jenkins 2.33.
  • JENKINS-35522 Improved credentials selection.

Version 1.11 (Apr 27, 2016)

  • Upgrade to new parent pom
  • Improve logging
  • Use JenkinsRule instead of HudsonTestCase for tests.

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)

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


  • No labels