Swarm Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID swarm Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
2.0 (archives)
Aug 03, 2015
Source Code
Issue Tracking
Pull Requests
Open Issues
Pull Requests
Kohsuke Kawaguchi (id: kohsuke)
Usage Installations 2014-Nov 1294
2014-Dec 1292
2015-Jan 1404
2015-Feb 1577
2015-Mar 1697
2015-Apr 1704
2015-May 1760
2015-Jun 1848
2015-Jul 2013
2015-Aug 2033
2015-Sep 2178
2015-Oct 2239

This plugin enables slaves to auto-discover nearby Jenkins master and join it automatically, thereby forming an ad-hoc cluster.
This plugin consists of two pieces:

  1. A self-contained CLI client that discovers a nearby Jenkins (via a UDP broadcast) and joins it
  2. A plugin that needs to be installed on Jenkins master to accept swarm clients

The primary use case of this came from "Jenkins slave appliance" — a virtual machine pre-packaged with the swarm client CLI — that someone can just grab and run.

With the swarm client, a person who's willing to contribute some of his computing power to the cluster just needs to run this virtual machine, and the cluster automatically gets additional resources. Because it's packaged as a VM, there is no need not worry about the builds/tests interfering with the host system or altering its settings unexpectedly.


  1. Install the swarm plugin from the update center
  2. Download the CLI agent from here.
  3. Run the CLI agent like java -jar path/to/swarm-client-jar-with-dependencies.jar. There's no required command option, but run with the -help option to see the available options.

Available Options

% java -jar swarm-client-jar-with-dependencies.jar -help
 -autoDiscoveryAddress VAL      : Use this address for udp-based auto-discovery -autoDiscoveryAddress VAL      : Use this address for udp-based auto-discovery
 -candidateTag VAL              : Show swarm candidate with tag only
 -description VAL               : Description to be put on the slave
 -disableClientsUniqueId        : Disables Clients unique ID.
 -disableSslVerification        : Disables SSL verification in the HttpClient.
 -executors N                   : Number of executors
 -fsroot FILE                   : Directory where Jenkins places files
 -help (--help)                 : Show the help screen
 -labels VAL                    : Whitespace-separated list of labels to be
                                  assigned for this slave. Multiple options are
 -master VAL                    : The complete target Jenkins URL like
                                  'http://server:8080/jenkins/'. If this option
                                  is specified, auto-discovery will be skipped
 -mode MODE                     : The mode controlling how Jenkins allocates
                                  jobs to slaves. Can be either 'normal'
                                  (utilize this slave as much as possible) or
                                  'exclusive' (leave this machine for tied jobs
                                  only). Default is normal.
 -name VAL                      : Name of the slave
 -noRetryAfterConnected         : Do not retry if a successful connection gets
 -password VAL                  : The Jenkins user password
 -passwordEnvVariable VAL       : Environment variable that the password is
                                  stored in
 -retry N                       : Number of retries before giving up. Unlimited
                                  if not specified.
 -showHostName (--showHostName) : Show hostnames instead of IP address
 -t (--toolLocation)            : A tool location to be defined on this slave.
                                  It is specified as 'toolName=location'
 -tunnel VAL                    : Connect to the specified host and port,
                                  instead of connecting directly to Jenkins.
                                  Useful when connection to Hudson needs to be
                                  tunneled. Can be also HOST: or :PORT, in
                                  which case the missing portion will be
                                  auto-configured like the default behavior
 -username VAL                  : The Jenkins username for authentication
 -t (--toolLocation)            : A tool location to be defined on this slave. -tunnel VAL                    : Connect to the specified host and port,                                  instead of connecting directly to Jenkins.                                  Useful when connection to Hudson needs to be                                  tunneled. Can be also HOST: or :PORT, in                                  which case the missing portion will be                                  auto-configured like the default behavio -username VAL                  : The Jenkins username for authentication


Error configuration : "xxx.xxx.xxx.xxx doesn't have the URL configuration yet"

This error indicates that the Jenkins master running at the given URL has never configured, and therefore the swarm client cannot determine its HTTP URL. To fix this problem, please go to the system configuration screen of this Jenkins, and click "submit".


Version 2.0 (2015 Aug 3)
Version 1.26 (2015 Jul 21)
  • Re-release of 1.25, some artefacts was not properly deployed. 
Version 1.25 (2015 Jul 21)
  • Correct #29232 - Set the HTTP Connection:close header to ensure the underlying socket is closed (see pull request 29)
  • Add a markdown formatted README to better describe the project for Github viewers
  • Improve end user reporting of hostname lookup errors (see pull request 30)
  • Make javadoc compile with JDK 8
Version 1.24 (2015 Apr 28)
Version 1.23 (2015 Apr 27)
Version 1.22 (2014 Nov 28)
Version 1.21 (2014 Nov 6)
  • Instead of constructing the tool location key, just use the existing descriptor (#25064, see pull request 20)
  • Use latest Jenkins LTS remoting library (1.580.1 Jenkins LTS version)
Version 1.20 (2014 Oct 8)
Version 1.19 (2014 Oct 6)
  • Correct bug introduced by 1.18 where the client did not work _unless_ you set tool locations (#24995, see pull request 18)
Version 1.18 (2014 Oct 2)
Version 1.17 (2014 Sep 30)
  • Add -noRetryAfterConnected and -retry options. These provide optional exit strategies for the default unlimited retry loop.
  • Require a well-formed master URL, ensuring trailing slash
  • [FIXED JENKINS-21892] Update swarm client to send CSRF token
  • Use latest releases of commons-codec, args4j, and remoting
Version 1.16 (2014 Jul 1)
Version 1.15
  • undocumented, or maybe a typo of 1.12?
Version 1.12, 1.11 (2014 Jan 15)
Version 1.10 (2013 Oct 21)
  • swarm 1.9 can't connect to current LTS as slave.jar too old (JENKINS-20138).
Version 1.9 (2013 May 18))
  • Add option for specifying Node.Mode(pull #3).
Version 1.8 (2012 Nov 21)
  • Changing broadcast to send a UDP packet payload of 128 bytes instead of 0
  • Allow slave connection without requiring UDP
  • Adds disableSslVerification option
Version 1.6 (2012 Mar 18)
  • fixed references from Hudson to Jenkins.
  • Swarm Client fails to connect to Jenkins when Authentication is enabled but Authorization is diabled (JENKINS-11663).
  • support remoting 2.12.
Version 1.5 (2011 Aug 11)
  • check whether user has SlaveComputer.CREATE permission.
  • allow authentication in swarm plugin (JENKINS-5504).
Version 1.4 (2010 Aug 14)
  • Fixed broken help links.
  • Node properties save correctly.
  • Added Japanese localization.
Version 1.3 (2010 Jan 14)
  • Fixed a packaging problem in the client jar (JENKINS-5275)
Version 1.2 (2009 Dec 30)
  • Minor text correction
Version 1.1 (2009 Jul 15)
  • Added the -master option.
Version 1.0 (2009 May 23)
  • Initial release


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

Add Comment