Configure and use nodetool with TLS

This guide explains how to configure and use nodetool with TLS on a database cluster that has client-to-node encryption enabled.

Prerequisites

Before you start, ensure you have:

  • Access to the database cluster

  • Client keystore and truststore files

  • Keystore and truststore passwords

When to configure nodetool for TLS

There are two ways to determine if you need to configure nodetool for TLS:

  1. Check if your cluster has client-to-node encryption enabled by running:

    kubectl get missioncontrolcluster CLUSTER_NAME -o yaml | grep -A 10 "client_encryption_options"

    Replace CLUSTER_NAME with the name of your cluster.

    If you see output similar to this, client-to-node encryption is enabled and you need to configure nodetool for TLS:

    client_encryption_options:
  enabled: true
  require_client_auth: true

  2. Look for this specific error message when running nodetool commands:

    error: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

    This error occurs when nodetool cannot establish a secure connection to the database node due to missing or invalid SSL certificates. If you see this error, you need to configure nodetool for TLS.

Configure nodetool for TLS

DataStax recommends using a Kubernetes ConfigMap to manage the nodetool TLS configuration. This ensures the configuration persists across node restarts and replacements.

  1. Create a ConfigMap with the nodetool SSL properties:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: CONFIG_MAP_NAME
  namespace: NAMESPACE
data:
  nodetool-ssl.properties: |
    -Dcom.sun.management.jmxremote.ssl.need.client.auth=true
    -Dcom.sun.management.jmxremote.registry.ssl=true
    -Djavax.net.ssl.keyStore=/mnt/client-keystore/keystore
    -Djavax.net.ssl.keyStorePassword=KEYSTORE_PASSWORD
    -Djavax.net.ssl.trustStore=/mnt/client-truststore/truststore
    -Djavax.net.ssl.trustStorePassword=TRUSTSTORE_PASSWORD

    Replace the following:

    • NAMESPACE: The namespace where your cluster is deployed

    • CONFIG_MAP_NAME: The name of the ConfigMap you want to create

    • KEYSTORE_PASSWORD: The password for the keystore

    • TRUSTSTORE_PASSWORD: The password for the truststore

  2. Apply the ConfigMap to your cluster:

    kubectl apply -f CONFIG_MAP_NAME.yaml

    Replace CONFIG_MAP_NAME.yaml with the path to the file you created in the previous step.

  3. Add the following to your MissionControlCluster spec to mount the ConfigMap in your database pods:

    apiVersion: missioncontrol.datastax.com/v1beta2
kind: MissionControlCluster
metadata:
  name: CLUSTER_NAME
spec:
  k8ssandra:
    cassandra:
      storageConfig:
        additionalVolumes:
          - name: nodetool-ssl-config
            configMap:
              name: nodetool-ssl-config
              items:
                - key: nodetool-ssl.properties
                  path: nodetool-ssl.properties
      containers:
        - name: cassandra
          volumeMounts:
            - name: nodetool-ssl-config
              mountPath: /opt/CONTAINER_USERNAME/.cassandra

    Replace the following:

    • NAMESPACE: The namespace where your cluster is deployed

    • CLUSTER_NAME: The name of your cluster

    • CONTAINER_USERNAME: The name of the server container user. Must be one of cassandra, dse, or hcd depending on the spec.k8ssandra.cassandra.serverType.

  4. Apply the modified MissionControlCluster object to your control plane:

    kubectl apply -f MISSION_CONTROL_CLUSTER_WITH_VOLUME.yaml

    Replace MISSION_CONTROL_CLUSTER_WITH_VOLUME.yaml with the path to the file you created in the previous step.

Run nodetool with TLS

To run nodetool commands with TLS enabled, use the --ssl flag with your credentials:

nodetool --ssl -u USERNAME -pw PASSWORD SUBCOMMAND

Replace the following:

  • USERNAME: The username for the database cluster

  • PASSWORD: The password for the database cluster

  • SUBCOMMAND: The nodetool command you want to run

The username and password parameters are only required if authentication is enabled.

For a complete list of nodetool commands, see the nodetool documentation for DataStax Enterprise (DSE) or Hyper-Converged Database (HCD).

Security considerations

When using nodetool with TLS:

  • Update the keystore and truststore paths to match your actual file locations.

  • Change the default passwords ("changeit") to your actual keystore and truststore passwords.

  • Ensure the client keystore and truststore files are accessible at the specified locations.

  • Secure the SSL properties file as it contains sensitive information.

When using the ConfigMap approach, DataStax recommends using a Kubernetes Secret instead of storing passwords in the ConfigMap.

Troubleshoot SSL issues

If you encounter SSL-related errors:

  1. Check that the keystore and truststore paths are correct.

  2. Verify that the passwords match your actual keystore and truststore passwords.

  3. Confirm that the client certificates are properly configured and valid.

  4. Ensure the database node’s JMX port is accessible and properly configured for SSL.

  5. Verify that the ConfigMap is properly mounted in the pod.

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com