Configuring TLS between eMake and agents

You can set up authentication and encryption based on Transport Layer Security (TLS) for communication between eMake and agents on Linux platforms. Authentication is bidirectional and mandatory if configured by either side—in other words, both eMake and the agent must provide credentials to the other party in the connection. If either party fails to provide credentials, if the credentials are invalid, or if the credentials are not acceptable for any reason, the connection between eMake and the agent is ended.

Both the eMake and the agent’s side of the connection configures the following attributes:

A certificate that identifies the principal—eMake or agent
A private key for the principal
A certificate authority chain that is used to verify the peer’s certificate
The list of common names and organizational units permitted to connect to the principal

The principal’s certificate and private key are from a single combined user-supplied PEM file; the certificate authority chain is taken from a single CA bundle file in PEM format. You provide the list of accepted common names (CNs) and organizational units (OUs) via a command-line argument.

Configuring eMake for TLS

Following are the eMake command line options for enabling TLS. If you use TLS for eMake, you must configure all agent machines as well. For details about configuring agent machines, see Configuring agents for TLS.

Command-Line Option Description

Command-Line Option	Description
--emake-ssl-cacert=< path_to_PEM_file >	Path to the certificate authority bundle file. For example, `--emake-ssl-cacert=cacert.pem`. This file contains root and intermediate certificates that are needed to complete the end-entity certificate chain. This file must be in PEM format.
--emake-ssl-keystore=< path_to_PEM_file >	Path to the combined certificate and keystore file used to identify eMake to agents. For example, `--emake-ssl-keystore=client-combined.pem`. This file must be in PEM format.
-emake-ssl-allow=< acl >	List of common names or organizational units (or both) that eMake will accept in agent certificates and thus permitted to connect to the agents, where `<acl>` 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`.

--emake-ssl-cacert=< path_to_PEM_file >

Path to the certificate authority bundle file. For example, --emake-ssl-cacert=cacert.pem. This file contains root and intermediate certificates that are needed to complete the end-entity certificate chain. This file must be in PEM format.

--emake-ssl-keystore=< path_to_PEM_file >

Path to the combined certificate and keystore file used to identify eMake to agents. For example, --emake-ssl-keystore=client-combined.pem. This file must be in PEM format.

-emake-ssl-allow=< acl >

List of common names or organizational units (or both) that eMake will accept in agent certificates and thus permitted to connect to the agents, where <acl> 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.

Configuring agents for TLS

Following are the settings that specify the TLS command-line arguments to runagent. If you use TLS for agents, you must configure eMake as well. For details about configuring eMake, see Configuring eMake for TLS.

The list of TLS options may be specified during installation as the Security Options input or later using the ecconfig -security command. If the the options are specified with ecconfig, the agent service must be restarted after the options are modified.

Option Description

Option	Description
-emakesecurity ssl	(Required) Indicates that the agents on this machine will use SSL.
-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.
-sslkeystore < path_to_PEM_file >	Path to your agent-side combined certificate and keystore file to be used to identify eMake to agents. This file must be in PEM format.
-sslallow < acl >	List of common names or organizational units (or both) that eMake will accept in agent certificates and thus permitted to connect to the agents, where `<acl>` 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`.

-emakesecurity ssl

(Required) Indicates that the agents on this machine will use SSL.

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

-sslkeystore < path_to_PEM_file >

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

-sslallow < acl >

Here is an example of using `ecconfig` to set up agent to eMake TLS communication.

sudo ecconfig -security "-emakesecurity ssl -sslcacert cacert.pem -sslkeystore server-combined.pem -sslallow cn=eric,ou=accelerator"

You can use ecconfig without options to check the values. Once the options are modified, 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.