Securing your remote agents
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:
Using a keytool, create a certificate for your server by entering the following command:
keytool -genkey -alias server -keyalg RSA -keystore server.ksThe server's certificate will be created. Export the certificate, so it can be shared with clients, by entering the following command:
keytool -export -alias server -keystore server.ks -file server_certEach client should now be able to access the server's certificate. Create a keystore for each client, by entering the following command:
keytool -genkey -alias client -keyalg RSA -keystore client.ksCreate a truststore for each client and import the server's certificate, by entering the command below. This establishes that the client "trusts" the server:
keytool -import -alias server -keystore client.ts -file server_cert
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:
- Add the system properties '
javax.net.ssl.keyStore=/path/to/server.ks' and 'javax.net.ssl.keyStorePassword=password' to your VM, by carrying out any of the following three steps:Set the SSL_OPTS environment variable to hold the '
javax.net.ssl.keyStore=/path/to/server.ks' and 'javax.net.ssl.keyStorePassword=password' properties.
e.g.export SSL_OPTS=-Djavax.net.ssl.keyStore=/path/to/server.ks -Djavax.net.ssl.keyStorePassword=password
To tell your agents where to find the keystore and truststore:
For each agent,
Tell your agent where to find the keystore and the trust store, by executing the following command to run the agent,
java -jar bamboo-agent-2.0-SNAPSHOT.jar <agentserverURL>including the following command line parameters,
-Djavax.net.ssl.keyStore=/path/to/client.ks -Djavax.net.ssl.keyStorePassword=password -Djavax.net.ssl.trustStore=/path/to/client.tswhere <agentserverURL> is the URL of the agent's server, e.g.
http://192.168.3.235:8085/agentServer/
For example,
java -Djavax.net.ssl.keyStore=/path/to/client.ks -Djavax.net.ssl.keyStorePassword=password
-Djavax.net.ssl.trustStore=/path/to/client.ts -jar bamboo-agent-2.0.jar http://192.168.3.235:8085/agentServer/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,
- 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,
- Shut down your Bamboo server and agents.
- 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="bamboo.jms.broker.uri">ssl://myhost:myport?wireFormat.maxInactivityDuration=0</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.