dbConfigUtility script

Usage

The setSSL command configures client-to-node encryption for Global Mailbox clients. This command tests the connection to the Cassandra cluster before saving the configuration or updating the shared truststore file. The configuration settings are stored on the com.ibm.mailbox.database.cassandra.ssl.*

The truststore used by Global Mailbox clients to authenticate servers is a shared truststore file located on the data center shared configuration directory (<config_root>/cassandra.truststore). All Global Mailbox clients in the data center share this truststore file. The shared truststore file is created the first time that the dbConfigUtility setSSL command is run with the --chooseTrust or --trustStoreFile options. The shared truststore type is JKS and the password is cassandra.

For client authentication, each Global Mailbox client uses its own private keystore file, specified by the --keyStoreFile option. This means that when client authentication is enabled on the Cassandra cluster, that the dbConfigUtility setSSL script must be run in every Global Mailbox node with the --keyStoreFile option. In addition, the key-certificate in the keystore must be trusted by the Cassandra cluster.

File location

install_dir/MailboxUtilities/admin/bin

Environments

Linux® or UNIX (dbConfigUtility.sh)
Windows (dbConfigUtility.bat)

Authorization

You must be a Global Mailbox administrator to view and modify the configuration of the applications with the dbConfigUtility script.

To use this script, you must provide your Global Mailbox administrator user ID and password.

Syntax

--parameter=value

Option descriptions

The following are the actions and options supported by the dbConfigUtility script:

adminUser=<user name>: Global Mailbox administrator user ID
adminPassword=<password>: Global Mailbox administrator password
enable: Whether to enable SSL. Valid values are true and false. This option should be enabled after client-to-node encryption has been enabled on the cluster.
protocol=<protocol>: The SSL/TLS protocol to connect to the server. Valid values are the values that are valid for the IBM® SDK, Java™ Technology Edition JRE. The default value is TLS. If the protocol is changed on the client_encryption_option section on the cassandra.yaml of the cluster, then the new protocol must be specified on this option for Global Mailbox client connections to Cassandra to succeed.
ciphers=<list of cipher suites>: Specifies the comma-separated list of cipher suites to use when SSL is enabled. The default is TLS_RSA_WITH_AES_128_CBC_SHA. The ciphers specified in this option must be a subset of the ciphers specified on the cipher_suites configured on the client_encryption_option section on the cassandra.yaml of the cluster.
trustAny: Indicates that any Cassandra server is trusted. This is the default.
chooseTrust: Connects to Cassandra servers, establishes a handshake, retrieves the server certificate chain, and prompts the user to choose a certificate from the chain to add to the shared truststore.
removeTrust=<alias>: Removes the certificate with the specified alias from the shared truststore. To find the aliases of the certificates stored in the shared truststore, run the dbConfigUtility showSSL command.
trustStoreFile=<path to file>: Specifies the fully-qualified path to a truststore file containing certificates to be added to the shared truststore.
trustStoreType: The type of the truststore file. This option is required if trustStoreFile is specified. Valid values are JKS and PKCS12.
trustStorePassword=<password>: The password of the truststore file. This option is required if trustStoreFile is specified. This password is used to open the truststore to copy its contents.
trustAlias=<alias>: Specifies the alias name of a certificate in the truststore file specified by --trustStoreFile that is added to the shared truststore.
unsetKeyStore: Removes the client authentication keystore setting after client authentication is disabled on the cluster.
keyStoreFile=<path to file>: Specifies the fully-qualified path to the keystore that is used by the client node for client authentication
keyStoreType=<JKS | PKCS12>: The type of the keystore file. This option is required if keyStoreFile is specified. Valid values are JKS and PKCS12.
keyStorePassword=<password>: The password of the keystore file. This option is required if keyStoreFile is specified.
keyAlias=<alias>: Specifies the alias name of the key-certificate on the keystore specified by the --keyStoreFile option to be used for client authentication. If not specified, the first key-certificate in the keystore is used.
servers=<list of hosts>: Specifies a list of server host names or IP addresses that are connected to when using the chooseTrust option. If not specified, connects to all the configured database servers.

Examples

The following code is an example of the setSSL command usage:

dbConfigUtility setSSL
  --adminUser=<user name>
  --adminPassword=<password>
  --enable=<true|false>
  --protocol=<protocol>
  --ciphers=<list of cipher suites>
  --trustAny
  --chooseTrust
  --removeTrust=<alias>
  --trustStoreFile=<path to file>
  --trustStoreType=<JKS | PKCS12>
  --trustStorePassword=<password>
  --trustAlias=<alias>
  --unsetKeyStore
  --keyStoreFile=<path to file>
  --keyStoreType=<JKS | PKCS12>
  --keyStorePassword=<password>
  --keyAlias=<alias>
  --servers=<list of hosts>

Confirmation

The showSSL command displays the current client-to-node encryption configuration on the console. This action takes no options. Use the following syntax:

dbConfigUtility showSSL