Securing your remote agents in Bamboo
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, go to Security 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.
Note that this solution doesn't cover artifact transfer between your remote agents and the server. To secure them, enable HTTPS (HTTP over SSL) access for Bamboo. See:
Configure your Bamboo server to use SSL
To instruct your Bamboo server to start using SSL so that agents will be able to authenticate the server, you need to modify the addresses used for communication between the agent and the server.
To configure your Bamboo server to use SSL:
If you are setting up Bamboo for the first time:
Launch the Bamboo Setup Wizard and change the protocol of the Broker URL to SSL.
i.e. ssl://host:port/
Setting up Broker URL during the installation doesn't change the Broker client URL to the same protocol. You can change the Broker client URL either directly in the Bamboo GUI (
> System > General configuration) or in the bamboo.cfg.xml file. Restart Bamboo to run it with the updated setup.
If you are configuring an existing installation of Bamboo:
- Shut down your Bamboo server and agents.
Change the protocol of your Broker URL and Broker client URL in the bamboo.cfg.xml file to SSL. Note, do not change the address of this URL.
<property name="bamboo.jms.broker.uri">ssl://myhost:myport</property><property name="bamboo.jms.broker.client.uri">failover:(ssl://myhost:myport)</property>For Bamboo 6.9 and later, add thesocket.verifyHostName=falseoption to thebamboo.jms.broker.client.uriproperty, as in the example below:<property name="bamboo.jms.broker.client.uri">failover:(ssl://bamboo:54663?socket.verifyHostName=false&wireFormat.maxInactivityDuration=300000)?initialReconnectDelay=15000&maxReconnectAttempts=10</property>Start up the Bamboo server.
- Start up the Bamboo agents. If your agents do not start up, please check that you have set up your certificates correctly.
Special considerations/troubleshooting
On a standard Bamboo installation, the above steps are sufficient to secure your agents. After they're done, Bamboo will automatically set up the key/trust stores and distribute certificates to the agents the moment the first time the agent connects to the server.
The automatic keystore management can be enabled or disabled by adding -Dbamboo.manage.jms.ssl=true/false to the server command line. When this variable is present, Bamboo will not decide whether to run automatic key management.
The following files are used by automatic key management:
- The Agent stores the keystore and truststore in BAMBOO_AGENT_HOME/xml-data/configuration/jmsclient.ks and BAMBOO_AGENT_HOME/xml-data/configuration/jmsclient.ts, respectively.
- Server stores the keystore in BAMBOO_HOME/xml-data/configuration/broker.ks
To force generation of new keystores and truststores, simply remove these files. They will be regenerated on the next restart.