This is the documentation for Cloudera Manager 5.1.x. Documentation for other versions is available at Cloudera Documentation.

Configuring TLS Authentication of Server to Agents

Required Role:

This is the second highest level of TLS security and requires that you provide a server certificate for the Server that is signed through a chain to a trusted root CA. You must also provide the certificate of the Certificate Authority (CA) that signed the Server's server certificate. If you are not working in a production environment, you can also use a self-signed server certificate.

Note: If the Server's server certificate or the associated CA certificate is missing or expired, the Agents do not allow communications with the Server.

Step 1: Configure TLS encryption.

If you have not already done so, you must configure TLS encryption to use this second level of security. For instructions, see Configuring TLS Encryption only for Cloudera Manager.

Step 2: Provide the Server's server certificate and CA certificate.

If you want to use a Certificate Authority-signed server certificate, you can use keytool to request a server certificate from an existing CA, you can skip down to Using a CA-signed server certificate. Alternatively, if you want to generate your own self-signed server certificate, you can use keytool to generate a public certificate for the Server, see Using a self-signed server certificate.

Using a CA-signed server certificate

Generate a new RSA key:

Use keytool provided by the Java SDK to create a new keystore containing a keypair for the Cloudera Manager server. Replace the

$ keytool -validity 180 -keystore cm_keystore.jks -alias jetty -genkeypair -keyalg RSA
Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  host_1.example.com
What is the name of your organizational unit?
  [Unknown]:  Support
What is the name of your organization?
  [Unknown]:  Cloudera
What is the name of your City or Locality?
  [Unknown]:  London
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:  GB
Is CN=host_1.example.com, OU=Support, O=Cloudera, L=London, ST=Unknown, C=GB correct?
  [no]:  yes
Enter key password for <jetty>
(RETURN if same as keystore password):

Create a Certificate Signing Request (CSR):
Use the key created in the previous step to create a CSR for the Cloudera Manager server.
```
$ keytool -certreq -alias jetty -keystore cm_keystore.jks > jetty.csr
Enter keystore password: 
```

Request a new server certificate:

To request a certificate from a recognised Certificate Authority (CA), provide the CSR generated in step 2. The example below uses a private CA created using OpenSSL.

$ openssl ca -config openssl.cnf -out jetty.crt -infiles jetty.csr
Using configuration from openssl.cnf
Enter pass phrase for cakey.pem:
Check that the request matches the signature
Signature ok
<--SNIP-->

Certificate is to be certified until Apr 19 10:49:41 2024 GMT (3650 days)
Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

Import CA trust certificates into the Cloudera Manager keystore:

Import the root and intermediate CA certificates to the keystore created in step 1. Generate a new RSA key.

$ keytool -import -keystore cm_keystore.jks -alias int_CA -file intermediate.crt
Enter keystore password:
Owner: CN=COE Intermediate Test CA, OU=Customer Operations, O=Cloudera, ST=London, C=GB
Issuer: CN=COE Root Test CA, OU=Customer Operations, O=Cloudera, L=Shoreditch, ST=London, C=GB
Serial number: 1
Valid from: Tue Apr 22 02:02:26 PDT 2014 until: Wed Apr 22 02:02:26 PDT 2015
<--SNIP-->

Trust this certificate? [no]:  yes
Certificate was added to keystore

$ keytool -import -keystore cm_keystore.jks -alias root_CA -file root.crt
Enter keystore password:
Owner: CN=COE Root Test CA, OU=Customer Operations, O=Cloudera, L=Shoreditch, ST=London, C=GB
Issuer: CN=COE Root Test CA, OU=Customer Operations, O=Cloudera, L=Shoreditch, ST=London, C=GB
Serial number: 928f80538cdfe523
Valid from: Tue Apr 22 01:58:53 PDT 2014 until: Sun Apr 21 01:58:53 PDT 2019
<--SNIP-->

Trust this certificate? [no]:  yes
Certificate was added to keystore

Import certificate into Cloudera Manager keystore:
Import the signed server certificate supplied by the CA, using the same alias that was used to create the key pair in step 1, so the key and the certificate are linked together in the keystore. Make sure you see the message, Certificate reply was installed in keystore.
```
$ keytool -import -keystore cm_keystore.jks -alias jetty -file jetty.crt
Enter keystore password:
Certificate reply was installed in keystore
```

Create trusted keystore:

Create a trusted keystore using the keytool command as in step 1. Generate a new RSA key. Import the CA intermediate and root certificates to this new keystore, in this case, trusted.jks. Alternatively, you can use the existing Cloudera Manager keystore, containing the CA intermediate and root certificates, as the trust store.

$ keytool -import -keystore trusted.jks -alias int_CA -file intermediate.crt
Enter keystore password:
Owner: CN=COE Intermediate Test CA, OU=Customer Operations, O=Cloudera, ST=London, C=GB
Issuer: CN=COE Root Test CA, OU=Customer Operations, O=Cloudera, L=Shoreditch, ST=London, C=GB
Serial number: 1
Valid from: Tue Apr 22 02:02:26 PDT 2014 until: Wed Apr 22 02:02:26 PDT 2015
<--SNIP-->

Trust this certificate? [no]:  yes
Certificate was added to keystore

$ keytool -import -keystore trusted.jks -alias root_CA -file root.crt
Enter keystore password:
Owner: CN=COE Root Test CA, OU=Customer Operations, O=Cloudera, L=Shoreditch, ST=London, C=GB
Issuer: CN=COE Root Test CA, OU=Customer Operations, O=Cloudera, L=Shoreditch, ST=London, C=GB
Serial number: 928f80538cdfe523
Valid from: Tue Apr 22 01:58:53 PDT 2014 until: Sun Apr 21 01:58:53 PDT 2019
<--SNIP-->

Trust this certificate? [no]:  yes
Certificate was added to keystore

Using a self-signed server certificate

Use keytool to generate a public certificate for the Server by typing the following command on the Server host:
```
$ keytool -validity 180 -keystore <path-to-keystore> -alias jetty -genkeypair -keyalg RSA
```
When prompted by keytool, create a password for the keystore. Save the password in a safe place.
When prompted by keytool, fill in the answers accurately to the questions to describe you and your company. The most important answer is the CN value for the question "What is your first and last name?" The CN must match the fully-qualified domain name (FQDN) or IP address of the host where the Server is running. For example, cmf.company.com or 192.168.123.101.
Important: For the CN value, be sure to use a FQDN if possible, or a static IP address that will not change. Do not specify an IP address that will change periodically. When agents connect to the server using TLS, they check whether the key uses the same name as the one they are using to connect to the server. If the names do not match, agents do not heartbeat.
On the Server host, run the following command to export the server certificate from your keystore in the binary DER format:
```
$ keytool -exportcert -keystore <path-to-keystore> -alias jetty -file server.der
```
Convert the binary DER format to a .pem file that can be used on the Agents by using openssl (available for download here.)
```
$ openssl x509 -out server.pem -in server.der -inform der
```

Step 3: Copy the Server's server .pem file to the Agents.

Copy the Server's server .pem file (for example, server.pem) to the Agent host in any directory. If you have used a CA-signed certificate, copy the CA's root certificate in PEM format to the Agent host. For example, copy the .pem file to /etc/cmf.

On the Agent host, open the /etc/cloudera-scm-agent/config.ini configuration file and edit the following properties in the /etc/cloudera-scm-agent/config.ini configuration file.

Property	Description
verify_cert_file	Enter the path to the Server's `server.pem` file. For example, `/etc/cmf/server.pem`.
use_tls	Set this property to `1`.

Repeat these steps on every Agent host.

Step 4: Enable TLS Encryption in Cloudera Manager.

Log into the Cloudera Manager Admin Console.
Select Administration > Settings.
Click the Security category.

Configure the following TLS setting:

Setting	Description
Use TLS Encryption for Agents	Enable TLS encryption between the Server and Agents.

Click Save Changes to save the settings.

Step 5: Restart the Cloudera Manager Server.

$ sudo service cloudera-scm-server restart

Step 6: Restart the Cloudera Manager Agents.

On every Agent host, restart the Agent:

$ sudo service cloudera-scm-agent restart

Step 7: Verify that the Server and Agents are communicating.

In the Cloudera Manager Admin Console, open the Hosts page. If the Agents heartbeat successfully, the Server and Agents are communicating. If not, check the Agent log /var/log/cloudera-scm-agent/cloudera-scm-agent.log which shows errors if the connection fails.

Page generated September 3, 2015.