Transport Layer Security Support and Custom Protocol Configuration

Coexistence and dependencies with Auto-TLS

Understand how advanced TLS feature flags interact with your existing Auto-TLS deployment to ensure proper certificate handling and service stability.

The following matrix details how advanced TLS feature flags complement or extend your baseline Auto-TLS implementation:

Table 1. Functional matrix for auto-TLS and advanced TLS feature flags
Feature	Primary function
Auto-TLS	Provisions and manages certificates (CA, host certificates, keystores, truststores) and enables baseline TLS (`ssl_enabled`) across core Hadoop services such as HDFS, YARN, ZooKeeper, HBase, Impala, etc.
Encrypt All Ports	Activating the `CMF_FF_ENCRYPT_ALL_PORTS` feature flag extends TLS encryption to internal communication ports outside the Auto-TLS scope, including Spark RPC, Kafka HTTP metrics, HDFS data transfer, and management service ports. You must provide pre-existing, valid certificates before enabling this flag.
Advanced TLS Control	Activating the `CMF_FF_TLS_ADVANCED_CONTROL` feature flag enforces protocol version selection (TLS 1.2 and TLS 1.3) and applies global cipher suite management across all TLS-enabled services.

System Requirements

Review the mandatory system prerequisites and environment baselines before enabling TLS 1.3 or advanced protocol controls across your cluster.


Component	Minimum Version & Functional Requirements
Java	TLS 1.3 is strictly supported only on environments running Java 17.0.11 or higher. Ensure your cluster JDK meets this baseline before changing configuration parameters to enable this protocol.
Python	TLS 1.3 requires Python 3.11 or higher. You must ensure the host environment meets this baseline version before configuring the protocol.
Cloudera Runtime	You must upgrade your cluster (or all managed clusters in a multi-cluster environment) to Cloudera Runtime 7.3.2 SP1 (7.3.2.10000) before you access and enable advanced TLS 1.3 feature flags.
Cloudera Manager	You must upgrade Cloudera Manager to version 7.13.2.10000 or higher to access and enable these features.

Multi-Cluster Compatibility Requirements

Cloudera Manager 7.13.2 SP1 enforces an automated compatibility check at startup. If you set either CMF_FF_TLS_ADVANCED_CONTROL or CMF_FF_ENCRYPT_ALL_PORTS to true, you must upgrade all managed clusters under that Cloudera Manager instance to Cloudera Runtime 7.3.2 SP1 or higher.

If any managed cluster runs a version lower than Cloudera Runtime 7.3.2 SP1, the Cloudera Manager Server stops during startup and fails to start:

Scenario A - Mixed Cloudera Runtime deployment

You upgrade Cloudera Manager to 7.13.2 SP1 and Cloudera Runtime Cluster 1 to 7.3.2 SP1, but Cloudera Runtime Cluster 2 remains on 7.1.9 SP1. Enabling the feature flags causes the Cloudera Manager Server to fail with the following log error:

Cloudera Manager cannot start: TLS_ADVANCED_CONTROL and/or ENCRYPT_ALL_PORTS is enabled 
but the following cluster(s) are running CDH versions older than CDH 7.3.2: [Cluster 2(CDH 7.1.9)]. 
Upgrade all clusters to CDH 7.3.2 or later, or disable the feature flag(s)...

Scenario B - Cloudera Manager-Only upgrade

You upgrade Cloudera Manager to 7.13.2 SP1, but you have not yet upgraded any managed clusters (Cloudera Runtime Cluster 1 and Cloudera Runtime Cluster 2 remain on 7.1.9 SP1). Enabling the feature flags causes the Cloudera Manager Server to fail with the following log error:

Cloudera Manager cannot start: TLS_ADVANCED_CONTROL and/or ENCRYPT_ALL_PORTS is enabled 
but the following cluster(s) are running CDH versions older than CDH 7.3.2: [Cluster 1(CDH 7.1.9), Cluster 2(CDH 7.1.9)]. 
Upgrade all clusters to CDH 7.3.2 or later, or disable the feature flag(s)...

Understanding the required sequence of steps

Both failure scenarios occur due to an incorrect execution sequence during the upgrade workflow:

Deployment Limitations

Understand architectural constraints and scope restrictions before configuring global cipher lists or deploying feature flags.

Scope of Global Cipher settings: The global TLS Cipher List configured in the Cloudera Manager UI (Administration > Settings > TLS Cipher List) applies exclusively to Cloudera Runtime cluster services. Cloudera Manager Server and Cloudera Manager Agents ignore this UI setting. To override default ciphers for Cloudera Manager components, edit their respective configuration files directly:
- Cloudera Manager Server: Set CMF_OVERRIDE_TLS_CIPHERS in /etc/default/cloudera-scm-server.
- Cloudera Manager Agents: Set cipher_list and server_cipher_list in /etc/cloudera-scm-agent/config.ini.
Cloudera Data Services on premises Incompatibility: You cannot install Cloudera Data Services on premises while CMF_FF_TLS_ADVANCED_CONTROL or CMF_FF_ENCRYPT_ALL_PORTS is active. You must disable both feature flags before initiating a Data Services installation.

Prerequisites

Enabling Advanced TLS and Encryption Feature Flags

Make the advanced configuration parameters visible in the Cloudera Manager User Interface and API by enabling backend feature flags.

warning

Deployment sequence: Upgrade all managed clusters to Cloudera Runtime 7.3.2 SP1 or higher before enabling CMF_FF_TLS_ADVANCED_CONTROL or CMF_FF_ENCRYPT_ALL_PORTS in /etc/default/cloudera-scm-server. If you enable these feature flags in mixed environments (where some Cloudera Runtime clusters run 7.3.2 SP1 while others remain on older Cloudera Runtime versions lower than 7.3.2 SP1) or un-upgraded environments (where Cloudera Manager is upgraded to 7.13.2 SP1, but all managed clusters still run older Runtime versions), the Cloudera Manager Server compatibility check fails, which prevents the Cloudera Manager server daemon from starting.
Keystore and truststore verification: Verify that all host keystores and truststores are active before enabling CMF_FF_ENCRYPT_ALL_PORTS. Enabling port encryption without valid PKI assets causes immediate service startup failures across the cluster.

Cloudera Manager hides the advanced TLS version controls (TLS 1.2, TLS 1.3) and global cipher configurations by default. You must enable the following two feature flags inside the Cloudera Manager Server configuration file to access them:

CMF_FF_TLS_ADVANCED_CONTROL: Enables advanced TLS version selection (TLS 1.2, TLS 1.3), global cipher suite distribution, and the per-component cipher inheritance option.
CMF_FF_ENCRYPT_ALL_PORTS: Enables TLS encryption enforcement on internal service ports that were previously unencrypted, providing comprehensive end-to-end encryption across all cluster nodes.

Log in to your Cloudera Manager Server host through SSH and open the /etc/default/cloudera-scm-server configuration file in a text editor:
```
sudo vi /etc/default/cloudera-scm-server
```

Append the following environment variables to the file:

export CMF_FF_TLS_ADVANCED_CONTROL=true
export CMF_FF_ENCRYPT_ALL_PORTS=true

Save the file and restart the Cloudera Manager Server daemon to apply the flags:
```
sudo systemctl restart cloudera-scm-server
```

Advanced TLS Control, Cipher Management, and Port Encryption Capabilities

Understand the UI properties and functional behaviors that take effect once you enable the advanced TLS control flags in Cloudera Manager.

Enabling CMF_FF_TLS_ADVANCED_CONTROL provides the following capabilities:

TLS Protocol version management

You can now enable TLSv1.2, TLSv1.3 only, or the combined TLSv1.2 and TLSv1.3 option (the default setting) through the UI or API. This option replaces the previous limitation of supporting only up to TLSv1.2.

When you enable the flag, Cloudera Manager updates the global TLS version default setting under Administration > Settings from TLSv1.2 to TLSv1.2 and TLSv1.3. Additionally, enabling this flag also activates global inheritance, allowing individual services to inherit the global TLS version setting by default instead of requiring manual per-service overrides.

Enabling the advanced TLS control flag disables and hides the previous per-service TLS version parameters, which support only TLSv1.2 and earlier and have no global inheritance option. Each service receives a replacement TLS version parameter that defaults to Copy From Global Settings option, automatically aligning all services with the global Cloudera Manager administration TLS version policy. You can override this setting on individual services to specify a custom TLS version for a specific component.

Cipher suite management

A new TLS Cipher List setting appears under Administration > Settings. When you configure ciphers here, Cloudera Manager automatically pushes them to all managed cluster services that are set to inherit global cipher settings. The default global cipher suite includes:

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Individual service configuration pages display cipher list parameters that default to Copy From Global Settings (stored internally as {{COPY_FROM_GLOBAL}}), ensuring services automatically inherit the global cipher policy. The new include-list parameters replace the previous per-service exclude cipher parameters. You can override the cipher list on individual services to specify custom cipher suites for specific components. Cluster services use this inheritance model by default starting with Cloudera Manager 7.13.2.10000. For information about cipher configuration, see Enabling TLS 1.3 and Customizing Cipher Suites in Cloudera Manager.

Automated Cloudera Manager Server reconfiguration

Enabling CMF_FF_TLS_ADVANCED_CONTROL automatically updates the internal transport configuration of the Cloudera Manager Server. This update allows the server to negotiate TLS 1.3 alongside TLS 1.2 and enforce the default CLOUDERA_2026 cipher allowlist (ECDHE+AES-GCM and native TLS 1.3 AES-GCM ciphers), replacing the legacy exclusion-based cipher policy.

This transition takes effect upon restarting the server; you do not need to manually configure ciphers in /etc/default/cloudera-scm-server. Your custom configuration overrides take precedence over these defaults regardless of whether you enable or disable the flag.

Automated Cloudera Manager Agent reconfiguration

Enabling CMF_FF_TLS_ADVANCED_CONTROL prompts the Cloudera Manager Server to notify host agents during heartbeat updates. Agents automatically update their cipher configuration and restart, switching from the legacy broad cipher list (HIGH:!DSS:!DH:!ADH:!DES:!3DES:!SHA1:!aNULL:!eNULL:!EXPORT:!SSLv2:!SSLv3:!TLSv1) to the restricted cipher list (ECDHE+AES-GCM ciphers). You do not need to perform any manual configuration on the agents. Your custom configuration overrides take precedence over these defaults regardless of whether you enable or disable the flag.

Enabling CMF_FF_ENCRYPT_ALL_PORTS allows you to:

Enable Universal Port Encryption: This forces TLS over all internal inter-service communication channels.
caution
You must verify that all cluster services are fully configured for TLS before enabling this flag in environments that previously operated without encryption. Ensure you provision and configure valid TLS certificates and truststores for those services prior to a restart, otherwise the cluster startup will fail.

Supported and Deprecated TLS Protocol Matrix

Review the active protocol options available when you activate advanced controls. Enabling these advanced control flags restricts the protocol configuration matrix, causing Cloudera Manager to drop insecure legacy protocols and prevent you from enabling them.

Supported TLS Protocol Options (Available to Enable):

When you enable the feature flag, Cloudera Manager supports the following TLS versions:

TLSv1.2
TLSv1.3
TLSv1.2 and TLSv1.3 (Default)

Removed Legacy Protocol Configurations (Unsupported):

Additionally, starting with Cloudera Manager 7.13.2.10000, Cloudera Manager drops support for the following protocol combinations when you enable the feature flag:

SSLv2Hello, TLSv1, TLSv1.1, and TLSv1.2
SSLv2Hello, TLSv1.1, and TLSv1.2
SSLv2Hello, and TLSv1.2

Reverting Feature Flag Settings

Understand how Cloudera Manager Server, host agents, and managed cluster services behave when you disable feature flags.

When you disable the feature flags in /etc/default/cloudera-scm-server, components revert to standard behavior as follows:


Component	Revert Behavior
Cloudera Manager Server	Cloudera Manager automatically reverts its primary communication protocol to TLS 1.2. Cipher selection falls back to legacy defaults (`MODERN2024` for TLS 1.3 or `MODERN2018` for TLS 1.2 only). Your custom configuration overrides take precedence over these defaults regardless of whether you enable or disable the flag.
Cloudera Manager Agent	On the next heartbeat, the Cloudera Manager Agent receives the disabled flag status, rewrites its local configuration, and restarts automatically to revert to the broad legacy cipher list. Your custom configuration overrides take precedence over these defaults regardless of whether you enable or disable the flag.
Managed Cluster Services	Services return to their previous configuration states. Once you disable the flag, Cloudera Manager ignores the global UI cipher and protocol values. Existing per-service configurations persist in the database and require no manual cleanup. You must restart the entire cluster for the updated configurations to take effect.

Recovering Cloudera Manager Server after startup failures (Multi-cluster environments)

Use this procedure to recover the Cloudera Manager Server if startup fails due to feature flag compatibility checks in mixed environments (where some Cloudera Runtime clusters run 7.3.2 SP1 while others remain on older Cloudera Runtime versions lower than 7.3.2 SP1) or un-upgraded environments (where Cloudera Manager is upgraded to 7.13.2 SP1, but all managed clusters still run older Runtime versions).

If Cloudera Manager fails to start after you activate feature flags, perform the following steps to restore administrative access:

Disable the TLS feature flags:
1. Log in to your Cloudera Manager Server host through SSH and open the /etc/default/cloudera-scm-server configuration file in a text editor:
```
sudo vi /etc/default/cloudera-scm-server
```
2. Set both feature flags to false (or remove the export lines):
```
export CMF_FF_TLS_ADVANCED_CONTROL=false
export CMF_FF_ENCRYPT_ALL_PORTS=false
```
  important
  If you configured custom server cipher overrides (CMF_OVERRIDE_TLS_CIPHERS), remove or revert that line as well.
Restart the Cloudera Manager Server process:
```
sudo systemctl restart cloudera-scm-server
```
Verify Cloudera Manager Server startup and health:
1. Confirm that Jetty starts successfully by checking the server log:
```
sudo tail -f /var/log/cloudera-scm-server/cloudera-scm-server.log | grep "Started Jetty"
```
2. Alternatively, verify connectivity using curl:
```
curl -sk -u admin:admin https://localhost:7183/api/version
```
Complete Cloudera Runtime Cluster upgrades:
Confirm that Cloudera Manager operates normally with feature flags disabled. Resume your cluster maintenance workflow and upgrade all managed clusters to Cloudera Runtime 7.3.2 SP1 or higher before you re-enable CMF_FF_TLS_ADVANCED_CONTROL or CMF_FF_ENCRYPT_ALL_PORTS.