ssl-manage

ssl-manage

Manage SSL certificates

SYNTAX

couchbase-cli ssl-manage [--cluster <url>] [--username <user>]
          [--password <password>] [--cluster-cert-info] [--node-cert-info]
          [--regenerate-cert <file>] [--set-node-certificate]
          [--upload-cluster-ca <file>]
          [--set-client-auth-state <enable|disable|mandatory>]
          [--set-client-auth-path <subject.cn|san.uri|san.dnsname|san.email>]
          [--set-client-auth-prefix <prefix>]
          [--set-client-auth-delimiter <delimiter>]
          [--client-auth] [--extended]

DESCRIPTION

This command allows users to manage their SSL and X.509 certificates.

OPTIONS

-c
--cluster

Specfies the hostname of a node in the cluster. See the HOST FORMATS section for more information on specifying a hostname.

-u
--user <username>

Specifies the username of the user executing the command. If you do not have a user account with permision to execute the command then it will fail with an unauthorized error.

-p
--password <password>

Specifies the password of the user executing the command. If you do not have a user account with permision to execute the command then it will fail with an unauthorized error. If this argument is specified, but no password is given then the command will prompt the user for a password through non-echoed stdin. You may also specify your password by using the environment variable CB_REST_PASSWORD.

--cluster-cert-info

Retrieves the cluster certificate and prints it to stdout.

--node-cert-info

Retrieves the node certificate and prints it to stdout.

--regenerate-cert <file>

Regenerates the cluster certificate and saves it to the file specified in the value fo this option.

--set-node-certificate

Sets the node certificate. Before running this command you must copy the node certificate into your installation. When this command is invoked the cluster will read the node certificate from the node specified and set it as the node certificate for that node.

--upload-cluster-ca <file>

Uploads the certificate specified to the cluster. The uploaded certificate will replace the cluster certificate in this cluster.

--set-client-auth-state <enable|disable|mandatory>

Sets the client certificate auth to following values:

  • disabled : no client certification

  • enabled : if the client presents a valid client certificate then we try and validate it. If the validation fails or no certificate is presented we fall back to the existing authentication methods

  • mandatory : the client has to present valid SSL certificate in order to access successfully authorise the connection.

--set-client-auth-path <path>: The field which will be used to extract the username from the certificate Currently only subject.cn, san.uri, san.email and san.dnsname are allowed

--set-client-auth-prefix <prefix> Optional. Prefix to be ignored from the field value

--set-client-auth-delimiter <delimiter> Optional. The delimiter can either be a string or a character, the parsing of the username ends when the delimter value is found.

--client-auth

This options used to get the client cert auth value

--extended

This option is used with the --cluster-cert-info and specifies that extended cluster certificate information should be printed to stdout.

HOST FORMATS

When specifying a host for the couchbase-cli command the following formats are expected:

  • couchbase://<addr>

  • <addr>:<port>

  • http://<addr>:<port>

It is recommended to use the couchbase://<addr> format for standard installations. The other two formats allow an option to take a port number which is needed for non-default installations where the admin port has been set up on a port other that 8091.

EXAMPLES

To get cluster certificate information run the following command.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --cluster-cert-info

Note that you can also get extended cluster certificat information by adding the --extended flag as shown below.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --cluster-cert-info --extended

To get node certificate information run the following command. Note that the node certificate will be from the node specified by the -c option.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --node-cert-info --extended

To automatically regenerate the cluster certificate and save the new certificate to a file at /root/new_cluster.cert run the following command.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --regenerate-cert /root/new_cluster.cert

Note that the command above should never be run if you are using X.509 certificates because using the --regenerate-cert command will generate an unsigned certificate for the cluster to use.

To update a node certificate you will first need to copy the new certificate to the certificate inbox folder on the node you wish to change the certificate. Once you have done this you can run the command below to tell the server to begin using the new certificate.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --set-node-certificate

To update the cluster certificate you can run the command below. Note that our certificate is located at /root/new_cluster.cert in this example.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --upload-cluster-ca /root/new_cluster.cert

To set the client cert auth to mandatory, following command can be run.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --set-client-auth mandatory

To get the client cert auth value, following command should be run.

$ couchbase-cli ssl-manage -c 192.168.1.5 -u Administrator \
 -p password --client-auth

ENVIRONMENT AND CONFIGURATION VARIABLES

CB_REST_PASSWORD Specifies the password of the user executing the command. This environment variable allows you to specify a default argument for the -p/--password argument on the command line. It also allows the user to ensure that their password are not cached in their command line history.

CB_REST_PASSWORD Specifies the password of the user executing the command. This environment variable allows you to specify a default argument for the -p/--password argument on the command line.