Configuring TLS between agents and Cluster Manager

2 minute read

CloudBees Build Acceleration automatically installs the agents to use encryption based on Transport Layer Security (TLS) between the agent and the Cluster Manager. The default is to use https to connect and verify the host name in the server, but accept self-signed certificates. The default level is known as relaxed and uses the Cluster Manager Secure Server port (8031 by default).

Configuring the agents to use a different security level can be done during installation by specifying the list of options as Security Options input in the installer or after by using the ecconfig -security command to specify the list of options. The options can be added in any order. Options for agent to eMake security may be specified at the same time.

Option Description

-cmsecurity <level>

Valid levels for the -cmsecurity option are:

none: use HTTP to connect to the Cluster Manager with no transport layer security. The agent must be configured to use port 8030 or the Cluster Manager Server port.

relaxed: use HTTPS but allows for self-signed certificates. This uses the Cluster Manager Secure Server port which is 8031 by default.

strict: use HTTPS to connect, verify the hostname and reject self-signed certificates. Using strict requires the use of the -sslcacert and -cmkeystore options. Also requires the Cluster Manager Secure Server port or 8031 by default.

-sslcacert < path_to_PEM_file >

Path to your certificate authority bundle file. This file contains root and intermediate certificates that are needed to complete the end-entity certificate chain. This file must be in PEM format.

-cmkeystore < path_to_PEM_file >

Path to your agent-side combined certificate and keystore file to be used to identify your agent to the Cluster Manager. This file must be in PEM format.

-cmallow < acl-list >

List of common names or organizational units (or both) that the Cluster Manager will accept in agent certificates and thus permitted to connect to the agents, where <acl-list> is a comma-separated list of elements of the forms cn=common_name and ou=organizational_unit. For example, to indicate that the common names eric and cindy are permitted, specify cn=eric,cn=cindy. To indicate that the common name eric and organizational unit accelerator are permitted, specify cn=eric,ou=accelerator.

The options may be specified using the ecconfig command. Once the options are modified, the agent service must be restarted. Here is an example of using ecconfig to set up strict agent to Cluster Manager communication.

sudo ecconfig -security "-cmsecurity strict -sslcacert myCAcert.pem -cmkeystore myCert.pem"

You can use ecconfig without options to check the values. Then the agent service must be started.

On Linux:

sudo /etc/init.d/ecagent restart

On Windows, open the Services control panel, select the CloudBees Build Acceleration Agent service, and choose Restart.