Use a cqlshrc file

You can use a .cqlshrc configuration file to set options for cqlsh, such as the default connection details, credentials, session preferences, and command-specific options.

Prerequisites

.cqlshrc structure and samples

The .cqlshrc file is written in INI format. It is divided into sections where the section name is enclosed in square brackets ([]), and the values in each section are represented as key-value pairs. Comment lines start with a semicolon (;), and in-line comments are prefaced with double semicolons (;;). For example:

[connection]
hostname = 127.0.0.1
port = 9042
request_timeout = 10

[authentication]
username = cassandra
password = cassandra

[history]
disabled = FALSE

[ui]
time_format = %Y-%m-%d %H:%M:%S%z
timezone = Etc/UTC
float_precision = 5
double_precision = 12

[tracing]
max_trace_wait = 10

[copy]
nullval = null
header = false
decimalsep = .
;; See sample cqlshrc files for more options and information

Your HCD installation includes the following sample .cqlshrc files with usage annotations and default values:

  • .cqlshrc.sample

  • .cqlshrc.sample.ssl

The location of the sample files depends on the type of installation:

  • Package installations: /etc/hcd/cassandra

  • Tarball installations: INSTALL_DIRECTORY/resources/cassandra/conf

Set permissions on .cqlshrc and cqlshrc_history

The contents of .cqlshrc is stored in plaintext, including passwords. To prevent unauthorized access to this information, set permissions on the .cqlshrc file:

chmod 440 $HOME/.cassandra/cqlshrc

Additionally, check the permissions on the $HOME/.cassandra/cqlshrc_history file, and modify them if needed.

Start cqlsh with a .cqlshrc file

By default, cqlsh looks for .cqlshrc at $HOME/.cassandra/cqlshrc or in the home directory generally. If found in the home directory, cqlsh moves .cqlshrc to ~/.cassandra/cqlshrc on the next invocation, and prints a message indicating that the file was moved. If you store your .cqlshrc file in a different location, you must specify the file path on the command line when starting cqlsh.

For the default location, you can start cqlsh without any additional arguments if the .cqlshrc file includes all required options:

cqlsh

For non-default locations, specify the path to your .cqlshrc file when you start cqlsh:

CQLSHRC environment variable
export CQLSHRC="~/path/to/cqlshrc"
--cqlshrc option
cqlsh --cqlshrc ~/path/to/cqlshrc

To override settings in the .cqlshrc file at runtime, specify any CQL shell options as environment variables or on the command line or when starting cqlsh.

Configure internal authentication in .cqlshrc

For basic internal authentication without SSL, specify the CQL role name and password in the [authentication] section. When connecting to a remote node, it can be helpful to include the node’s hostname and port in the [connection] section.

To start cqlsh with your preferred keyspace selected, set the keyspace option in the [authentication] section.

The following example connects to the local host with internal authentication, and it selects the cycling keyspace as the default context for the cqlsh session:

[connection]
hostname = 127.0.0.1
port = 9042

[authentication]
username = DATABASE_ROLE_NAME
password = DATABASE_ROLE_PASSWORD
keyspace = cycling

Configure SSL encryption in .cqlshrc

Connections to HCD 2.0 clusters through a Mission Control CQL gateway use a gateway Secure Connect Bundle (SCB) that automatically configures SSL for client-to-node connections.

The following procedure is for manual SSL configuration without a Mission Control CQL gateway.

To connect to nodes with client-to-node encryption enabled, cqlsh uses its own key and a certificate that is signed by the same root Certificate Authority (CA) as the cluster’s nodes or a different CA.

  1. On the machine where you are running cqlsh, create a client.conf configuration file:

    touch client.conf

  2. In the client.conf file, set the following options:

    [ 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

    Replace the placeholder with the values for your environment:

    • CA_DN: Distinguished name for the Certificate Authority. Note that this value is also the name of the section in the client.conf file that contains the distinguished name information.

    • ROOTCA_CQLSH_PASSWORD: Password for the root CA used by cqlsh.

    • CC: Country code for the Certificate Authority.

    • ORG_NAME: Organization name for the Certificate Authority.

    • CLUSTER_NAME: Cluster name for the Certificate Authority.

    • CA_CN: Common name for the Certificate Authority.

  3. Generate a key and certificate for cqlsh using your client.conf file.

    Change the keyout and out file names and paths as needed for your environment.

    openssl req -newkey rsa:2048 \
  -nodes \
  --keyout client_key.key \
  -out signing_request.csr \
  -config 'client.conf'

  4. Sign the cqlsh certificate using the same root CA as the target node.

    Replace the arguments in the following command with the values for your environment and certificate files:

    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

  5. In your .cqlshrc file, add or edit the SSL options.

    The following example uses default values and placeholders. For additional examples, see the cqlshrc.sample.ssl file.

    Note the section names; each option must be set under the appropriate section.

    [authentication]
username = DATABASE_ROLE_NAME
password = DATABASE_ROLE_PASSWORD

[connection]
hostname = 127.0.0.1
port = 9042
factory = cqlshlib.ssl.ssl_transport_factory

[ssl]
certfile = path/to/rootca.crt
validate = true
userkey= client_key.key
usercert = client_cert.crt_signed

[certfiles] ;; Optional
10.209.182.160 = ~/keys/NODE_NAME.cert
10.68.65.199 = ~/keys/NODE_NAME.cert
; NODE_IP = PATH/TO/CERTIFICATE
    Authentication

    In the [authentication] section, provide the CQL role name and password to authenticate with the database. If using Kerberos authentication, provide the necessary Kerberos credentials instead of the CQL role name and password.

    Hostname and port

    In the [connection] section, specify the IP address or hostname and port of the node to connect to. The default connection is 127.0.0.1:9042.

    Factory

    In the [connection] section, factory must be set to cqlshlib.ssl.ssl_transport_factory to use SSL.

    Certificates

    In the [ssl] section, certfile specifies the default root certificate file to use for SSL connections.

    You can use the optional [certfiles] section to specify host-specific certificate files that override the default certfile for specific nodes. When generating these certificates, make sure the CN is set to the node’s hostname.

    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 your HCD truststore.jks truststore.
    User key and user certificate

    If require_client_auth = true in cassandra.yaml, generate a PEM file of the certificate with no keys ($USER.cer.pem) and a PEM file of the key with no certificate ($USER.key.pem), and then set the path to these files in userkey and usercert in .cqlshrc.

    The userkey and usercert options in the [ssl] section specify the key certificate and the signed security certificate that cqlsh will use when connecting to an SSL-encrypted node.

    Validation

    By default validate is true (enabled). When enabled, you must create a PEM key to be used in the .cqlshrc file. For example:

    keytool -importkeystore -srckeystore .keystore -destkeystore $USER.p12 -deststoretype PKCS12
openssl pkcs12 -in $USER.p12 -out $USER.pem -nodes

    This pem key is required because the host in the certificate is compared to the host of the target machine. The SSL certificate must be provided either in .cqlshrc or as an environment variable.

    Environment variables

    The environment variables SSL_CERTFILE and SSL_VALIDATE override options set in .cqlshrc. For example:

    export SSL_CERTFILE='path/to/rootca.crt'

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | 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: Contact IBM