Skip to end of metadata
Go to start of metadata

This page applies to remote agents and not elastic agents. Elastic agents are secured automatically by the Bamboo server and no additional steps are required.

We strongly recommend that you do not enable remote agent installation without securing them on any Bamboo instance accessible from a public or untrusted network. Creating remote agents is disabled by default. If you choose to enable your remote agents without securing them, please read this Security Advisory to understand the security implications.

You can secure your remote agents by configuring them to use SSL (Secure Sockets Layer). This protocol provides a secure mechanism for communication between your Bamboo server and remote agents. The information below describes how to configure your remote agents to use SSL.

On this page:

Step 1. Create keys, stores and certificates

The first step in configuring your remote agents to use SSL is to create the required keys, stores and certificates. These artefacts are created using a keytool, as described below:

SSL relies on keys being set up on your server and clients (i.e. agents). To securely store these keys, keystores (databases of keys) need to be created. A certificate is then created by the server (and optionally on the clients, but not for this configuration) to allow publication of the server's key. To establish that the client "trusts" the server, this server certificate is then imported into a truststore (key database file that contains the public keys for a specific server) created on the client.

To create the required keys, stores and certificates for your server and agents:

  1. Using a keytool, create a certificate for your server by entering the following command:

  2. The server's certificate will be created. Export the certificate, so it can be shared with clients, by entering the following command:

  3. Each client should now be able to access the server's certificate. Create a keystore for each client, by entering the following command:

  4. Create a truststore for each client and import the server's certificate, by entering the command below. This establishes that the client "trusts" the server:

Step 2. Tell your Bamboo server and agents where to find the stores

The second step in configuring your agents to use SSL is to instruct your Bamboo server and agents to use the keystores and truststores that you have just created.

To tell your server where to find the keystore:

  1. Add the system properties '' and '' to your VM, by carrying out any of the following three steps:
    • Set the SSL_OPTS environment variable to hold the '' and '' properties.

To tell your agents where to find the keystore and truststore:

For each agent,

  1. Tell your agent where to find the keystore and the trust store, by executing the following command to run the agent,

    including the following command line parameters,

    where <agentserverURL> is the URL of the agent's server, e.g.

For example,

Step 3. Configure your Bamboo server to use SSL

Once the server and agents know where to find the keystores and truststores, the final step is to instruct your Bamboo server to start using SSL so that agents will be able to authenticate the server.

To configure your Bamboo server to use SSL:

If you are setting up Bamboo for the first time,

  1. Launch the Bamboo Setup Wizard and change the protocol of the 'Broker URL' to 'SSL'.
    i.e. ssl://host:port/

Or, if you are configuring an existing installation of Bamboo,

  1. Shut down your Bamboo server and agents.
  2. Change the protocol of your 'Broker URL' in the bamboo.cfg.xml file to 'SSL'. Note, do not change the address of this URL.
    e.g. <property name="">ssl://myhost:myport?wireFormat.maxInactivityDuration=0</property>
  3. Start up the Bamboo server.
  4. Start up the Bamboo agents. If your agents do not start up, please check that you have set up your certificates correctly.


  1. Don't forget to change "" to use ssl as well

  2. The server steps in Step 2 say "carrying out any of the following three steps" but only one is listed. Are there other options?

    1. Thanks for pointing that out. There are no alternative steps, the reference to three steps should have been removed.



  3. According to Remote agents are unable to validate the failover and connect to the server the "" value should always be set to "" so should this page really use 'host: port' and 'myhost:myport' in step 3?

    1. binds the broker to all interfaces. "host" binds it to a single interface. With "host" you (may) get a more secure setup because you don't necessarily have to rely on firewalls to protect your brokers.

  4. The last time I was running through this process I believe I got this working correctly. This time however I have run into a problem (whose solution I have now found) but it made me wonder if these directions are missing a step or if I missed a step in some other part of the process this time which I did not miss the last time.

    Adding the properties to SSL_OPTS was not enough, by itself, to allow the brokers to work correctly. Nothing that I can see uses that variable by default. I needed to add those arguments to JAVA_OPTS instead for them to work.

    I seem to recall seeing the SSL_OPTS="" JAVA_OPTS="$SSL_OPTS" pair in the documentation before but cannot find it now.

    Additionally, the SSL_OPTS line is not valid shell (there are invalid spaces around the equals sign and no quotes on the right-hand side of the assignment). Also, the erroneous "one of the following three steps" text that was previously removed was added back recently for some reason.

    1. I just confirmed that adding keystore defines to JAVA_OPTS was necessary with Bamboo 5.5.1.