Securing your remote agents

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.

Please note that you cannot set up client certificates in Bamboo due to limitations with Active MQ. Thus, while encryption works both ways between the server and client in this recommended configuration, authentication is only one-way. That is, the clients (i.e. agents) can authenticate the server, but the server will not be able to authenticate the clients (i.e. agents).

このページの内容

関連ページ

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.ks
```
The 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_cert
```
Each 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.ks
```
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:
```
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:
- (Bamboo or Bamboo EAR-WAR) 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
```
  Or,
- (Bamboo only) Add 'javax.net.ssl.keyStore=/path/to/server.ks' and 'javax.net.ssl.keyStorePassword=password' as additional properties to the wrapper.conf file.
  e.g.
```
wrapper.java.additional.4=-Djavax.net.ssl.keyStore=/path/to/server.ks
wrapper.java.additional.5=-Djavax.net.ssl.keyStorePassword=password
```
  Or,
- (Bamboo EAR-WAR only) Make the 'javax.net.ssl.keyStore=/path/to/server.ks' and 'javax.net.ssl.keyStorePassword=password' properties visible to the VM, as per the instructions for your webserver.

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.ts

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

http://192.168.3.235:8085/agentServer/

例:

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.

Child pages

Securing your remote agents

Step 1. Create keys, stores and certificates

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

Step 3. Configure your Bamboo server to use SSL