Plugin Information |
---|
View SSH Agent 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 Agent Plugin
This plugin allows you to provide SSH credentials to builds via a ssh-agent in Jenkins.Requirements
Currently all Windows nodes (including the master) on which this plugin will be used must have the Apache Tomcat Native libraries installed. As of 1.0 should be unnecessary for Unix nodes. As of 1.14 unnecessary if ssh-agent
is installed.
Configuring
First you need to add some SSH Credentials to your instance:
Jenkins | Manage Jenkins | Manage Credentials
Note that only Private Key based credentials can be used.
Then configure your build to use the credentials:
And then your build will have those credentials available, e.g.
From a Pipeline job, use the sshagent
step.
Installation Example: MacOSX (10.7.5)
Irrelevant in 1.14+ when ssh-agent
is available in the path.
Prerequisites:
- JDK7. The tomcat native libraries target the java 7 version.
- APR - this seems to be preinstalled in /usr/lib/apr.
Note that tomcat itself is not needed. This works fine with winstone (just running jenkins jar from command line).
Download and extract the tomcat native library: http://tomcat.apache.org/download-native.cgi
tar -zxvf tomcat-native-1.1.XX-src.tar.gz
Build the native library:
cd tomcat-native-1.1.XX/jni/native ./configure --with-apr=/usr/bin/apr-1-config make && sudo make install
Build the java interface:
cd .. export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home ant build ant jar
Copy the output jar somewhere suitable for inclusion in your jenkins CLASSPATH.
Set environment variables prior to starting jenkins:
export DYLD_LIBRARY_PATH=/usr/local/apr/lib export CLASSPATH=/path/to/tomcat-native-1.1.XX.jar java -jar jenkins.war
Additionally, you might have to add bouncycastle to your JCE providers. If you attempt to use the plugin and get an exception like the following:
java.lang.IllegalStateException: BouncyCastle must be registered as a JCE provider
Then you may need to configure the jce provider. One way is to do this right in the JRE, so if Jenkins is using the same jdk as above, edit
/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/security/java.security, and add the following line:
security.provider.11=org.bouncycastle.jce.provider.BouncyCastleProvider
Then, restart jenkins.
From there, configure using the instructions above.
Version History
Version 1.17 (2018-10-02)
- Did not properly interact with
withDockerContainer
when run on a machine withDISPLAY=:0
set.
Version 1.16 (2018-07-30)
Version 1.15 (2017-04-06)
issue@42093 Fixed quoting for askpass in command-line implementation.
Version 1.14 (2017-02-10)
- JENKINS-36997 New default implementation that uses command-line
ssh-agent
. Should fix various problems with crypto APIs,docker.image(…).inside {sshagent(…) {…
}}, etc. - JENKINS-38830 Track credentials used in the wrapper.
- JENKINS-35563 Fixes to credentials dropdown.
Version 1.13 (2016-03-03)
- JENKINS-32120 Register Bouncy Castle on the remote agent by using Bouncy Castle API plugin
Apparently does not work in some versions of Jenkins; see JENKINS-36935.
Version 1.12 (2016-03-03)
- Wrong release. Release process broken due a network issue.
Version 1.11 (2016-03-03)
- JENKINS-35463 First release using bouncycastle-api-plugin
Version 1.10 (2016-03-03)
- JENKINS-27152 / JENKINS-32624 Use a standardized temporary directory compatible with Docker Pipeline.
Version 1.9 (2015-12-07)
Changelog unrecorded.
Version 1.8 (2015-08-07)
Version 1.7 (2015-06-02)
- Fixed a socket and thread leak (issue #27555)
Version 1.6 (2015-04-20)
- SSH agent socket service thread shouldn't keep JVM alive.
Version 1.5 (2014-08-11)
- Add support for multiple credentials
- Add support for parameterized credentials
Version 1.4.2 (2014-08-11)
- Fix for JENKINS-20276
- WARNING: Due to classpath conflicts, this plugin will not work if 1.518 <= Jenkins Version < 1.533 (i.e. 1.518 broke it, 1.533 fixed it)
Version 1.4.1 (2013-11-08)
- Switch from f:select to c:select so that in-place addition of credentials is supported when the credentials plugin exposes such support
- WARNING: Due to classpath conflicts, this plugin will not work if 1.518 <= Jenkins Version < 1.533 (i.e. 1.518 broke it, 1.533 fixed it)
Version 1.4 (2013-10-08)
- Minor improvement in exception handling
- Minor improvement in fault reporting
- Update JNR libraries
- WARNING: Due to classpath conflicts, this plugin will not work if 1.518 <= Jenkins Version < 1.533 (i.e. 1.518 broke it, 1.533 fixed it)
Version 1.3 (2013-08-09)
- Set-up SSH Agent before SCM checkout, this way GIT can use the ssh agent. (Contributed by Patric Boos)
- Upgrade to SSH Credentials 1.3
Version 1.2 (2013-08-07)
- Upgrade to Credentials plugin 1.6 and SSH Credentials plugin 1.0. This now allows serving multiple private keys from the users home directory, e.g. ~/.ssh/id_rsa, ~/.ssh/id_dsa and ~/.ssh/identity
Version 1.1 (2013-07-04)
- If BouncyCastleProvider is not registered, try to register it ourselves anyway... this should make installation and configuration even easier.
Version 1.0 (2012-11-01)
- Using jnr-unixsocket have been able to remove the requirement on Apache Tomcat Native for unix nodes. Likely still require the Apache Tomcat Native for Windows nodes.
Version 0.1 (2012-10-26)
- Initial release
8 Comments
Unknown User (qxo)
for "java.lang.IllegalStateException: BouncyCastle must be registered as a JCE provider"
need copy bcprov*.jar to jre/lib/ext
jre/lib/ext> wget http://repo1.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.48/bcprov-jdk15on-1.48.jar
Unknown User (jsirex)
Unable to amke it works:
Running shell commands:
Any tips?
Unknown User (tkopal)
We tried to use this plugin, it works perfect on linux slaves, but fails on windows slaves. After digging deeper, we found that the java ssh-agent implementation is incompatible with cygwin tools. Java agent seems to be creating a pipe on windows for communication between ssh-agent and clients (as the unix-default local socket implementation is not available on windows), however cygwin ssh-clients (ssh, ssh-add, etc.) expect a text file with TCP socket details.
Anybody suceeded tu run this on windows with cygwin oriented ssh clients?
Unknown User (mi_la)
See https://github.com/jenkinsci/ssh-agent-plugin/pull/2 with an implementation of ssh-agent which uses native programs on jenkins slaves (ssh-agent, ssh-add).
Unknown User (gnuninu)
Is there any way to hide/encrypt the private key from the GUI in order to make it not visible to the admin as well ?
Similar mechanisms are used by Semaphore or ansible tower I wonder whether it's possible to achieve the same on Jenkins...
Unknown User (danixu86)
Hello,
The ability to use a private key on Jenkins Master as source has dissapeared. This change is forever?
Greetings
Unknown User (clook)
When using a ssh user + private key credential, the private key must be terminated with a new line or you will get the following error:
...even if the same credential (not terminated with new line) works flawlessly for a git SCM checkout with github branch source on a Jenkins pipeline.
Unknown User (jglick)
Please do not use the comment feature of the wiki. If you have usage questions, use the users’ list; if you believe you have discovered a bug, please file a report in JIRA with complete steps to reproduce from scratch.