Use a cqlshrc file

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

`cqlshrc` samples

For configuration examples, see the sample cqlshrc files included with your DSE installation:

cqlshrc.sample
cqlshrc.sample.ssl
cqlshrc.sample.kerberos

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

Package installations: /etc/dse/cassandra
Tarball installations: INSTALL_DIRECTORY/resources/cassandra/conf

Set connection options in `cqlshrc`

For remote nodes, set the hostname, port, and ssl options in the [connection] section of your cqlshrc file.

For a complete list of options, see the CQL shell reference documentation.

Set authentication credentials in `cqlshrc`

In your cqlshrc file, edit or add an [authentication] section with the username and password:

[authentication]
username = DATABASE_ROLE_NAME
password = DATABASE_ROLE_PASSWORD

Set Kerberos credentials in `cqlshrc`

Configure your cqlshrc file to connect to a Kerberos-enabled cluster. For an example, see the cqlshrc.sample.kerberos file.

The CQL shell requires the following settings for Kerberos authentication. The following example uses default values.

[connection]
hostname = 192.168.1.2
port = 9042

[kerberos]
service = dse
qops = auth

Service principal

The service_principal setting must be consistent and present in all applicable locations:

In the kerberos_options section of the dse.yaml file.
In the keytab.
In the cqlshrc file, the service principal is split into the hostname and service options. Together, these options must match the service_principal set in the dse.yaml file, or they must be set as environment variables.

Kerberos environment variables

The environment variables KRB_HOST, KRB_SERVICE, and KRB_PRINCIPAL override the corresponding options set in dse.yaml.

The environment variables KRB_SERVICE and QOPS override the corresponding options in the cqlshrc file.

If not set as environment variables or in cqlshrc, the default values are used. The default for qops is auth. The default for service is dse.

QOP

On the client (cqlsh) side, the qops option is a comma-delimited list of the QOP values allowed by the client for the connection. The client qops list in the cqlshrc file must contain at least one of the QOP values that are specified on the server. The client can have multiple qops values, but the server can have only one QOP value that is set in dse.yaml.

Kerberos with SSL

To use Kerberos with SSL, you must configure the settings for both Kerberos and SSL encryption, which are described in the next section. The supported environmental variables are KRB_SERVICE, SSL_CERTFILE, and SSL_VALIDATE.

Configure SSL encryption in `cqlshrc`

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.

On the machine where you are running cqlsh, create a client.conf configuration file:
```
touch client.conf
```
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.
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'
```

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

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.

[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

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 DSE 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'

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, start cqlsh without any additional arguments:

cqlsh

For non-default locations, start cqlsh with the CQLSHRC environment variable and the path to your cqlshrc file:

cqlsh CQLSHRC="~/path/to/cqlshrc"

Override `cqlshrc` settings at runtime

You can override settings in the cqlshrc file at runtime by specifying them as command-line options when starting cqlsh.