Connecting to SSL-enabled Nodes using cqlsh

Use the CQL shell (cqlsh) to connect to nodes where SSL is configured for client-to-node connections. cqlsh can use its own key and certificate that can either be signed by the same root Certificate Authority (CA) used for nodes in the cluster or by a different CA.

Use the DataStax Enterprise sample cqlshrc.sample.ssl file as a starting point. See the SSL example for reference.

The default location of the cqlshrc.sample.ssl file depends on the type of installation:

  • Package installations: /etc/dse/cassandra/cqlshrc.sample.ssl

  • Tarball installations: <installation_location>/resources/cassandra/conf/cqlshrc.sample.ssl

The environment variables (SSL_CERTFILE and SSL_VALIDATE) override any options set in the cqlshrc file.

If problems authenticating occur, then use the --debug option to show CQL shell settings and connection details.


  1. Create a client.conf configuration file:

    touch client.conf
  2. Edit the client.conf file and add the following settings:

    # <client.conf>
    [ req ]
    distinguished_name = <CA_DN>
    prompt             = no
    output_password    = <rootca-cqlsh_password>
    default_bits       = 2048
    [ <CA_DN> ]
    C  = <CC>
    O  = <org_name>
    OU = <cluster_name>
    CN = <CA_CN>
  3. Generate a separate key and certificate for cqlsh, using the client.conf file you created in the previous step.

    openssl req -newkey rsa:2048 \
    -nodes \
    -keyout <client_key.key> \
    -out <signing_request.csr> \
    -config `client.conf`
  4. Sign the certificate using the same root CA certificate used on the node where you are running cqlsh. You created the root CA to sign DSE node certificates for SSL.

    openssl x509 -req -CA '<path/to/rootca.crt>' \
    -CAkey '<path/to/rootca.key>' \
    -in <signing_request.csr> \
    -out <client_cert.crt_signed> \
    -days 3650 \
    -CAcreateserial \
    -passin pass:<rootca_password>
    • rootca.crt

      Certificate used to sign (authorize) DSE node SSL certificates.

  5. Copy the cqlshrc.sample.ssl file to the ~/.cassandra directory. The following example uses the default location for a package installation:

    cp /etc/dse/cassandra/cqlshrc.sample.ssl ~/.cassandra
  6. Rename the file to cqlshrc. The file is typically located in ~/.cassandra/cqlshrc.

    If cqlsh finds the cqlshrc file located in the home directory, cqlsh moves the file to ~/.cassandra/cqlshrc upon its next invocation and shows a message that the file moved.

  7. Specify the location of the SSL certificate file either using the SSL_CERTFILE environment variable or the [ssl] cqlshrc parameters.

    If you created your own root CA, use the root certificate rootca.crt. If using an external certificate from a well-known root CA, extract the certificate from the <dse-truststore.jks> truststore.

    • Environment variable:

      Use the SSL_CERTFILE variable to specify the path to the certificate file:

      EXPORT SSL_CERTFILE='<path/to/rootca.crt>'
    • cqlshrc parameter:

      In the [ssl] section of the cqlshrc file, use the certfile parameter to specify the path to the root certificate:

      certfile = <path/to/rootca.crt>
      validate = true
      userkey = <client_key.key>
      usercert = <client_cert.crt_signed>

      Certificate used to sign (authorize) DSE node SSL certificates.


      Key certificate used for cqlsh.


      Signed security certificate to use when connecting to a node using cqlsh.

  8. Restart cqlsh.

SSL example

DataStax Enterprise provides a sample cqlshrc.sample.ssl file that you can use as a starting point.

username = fred
password = !!bang!!$

hostname =
port = 9042
factory = cqlshlib.ssl.ssl_transport_factory

certfile = <path/to/rootca.crt>
; Optional, true by default.
validate = true
userkey = <client_key.key>
usercert = <client_cert.crt_signed>

; Optional section, overrides the default certfile in the [ssl] section. = ~/keys/cassandra01.cert = ~/keys/cassandra02.cert

When validate is enabled, you must create a Policy Enforcement Manager (PEM) key which is used in the cqlshrc file.

This PEM key is required because the host in the certificate is compared to the host of the machine to which it is connected. The SSL certificate must be provided either in the configuration file or as an environment variable. The environment variables (SSL_CERTFILE and SSL_VALIDATE) override any options set in this file.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

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,