A newer version of this documentation is available.

View Latest

ssl-manage

      +

      Manage SSL certificates

      SYNOPSIS

      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 <path>]
          [--client-auth] [--extended]

      DESCRIPTION

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

      OPTIONS

      -c
      --cluster

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

      -u
      --username <username>

      Specifies the username of the user executing the command. If you do not have a user account with permission 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 permission 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 of 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 <path>

      Specifies a path to the client auth configuration file. This file should contain the state of client auth and one or more prefixes. The state defines whether or not client auth should used. The possible values for this field are below:

      • disabled: no client certification

      • enable: 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 authorize the connection.

      The prefixes section should contain one or more prefixes and each prefix should contain a path, prefix, and delimiter. More information about these sub-fields is below:

      • 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

      • prefix: Optional. Prefix to be ignored from the field value

      • delimiter: Optional. The delimiter can either be a string or a character, the parsing of the username ends when the delimiter value is found.

      Below is an example of what a client auth configuration file might look like:

        {
          "state": "enable",
          "prefixes": [
            {
              "path": "subject.cn",
              "prefix": "www.cb-",
              "delimiter": "."
            }
          ]
        }
      --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 certificate 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_USERNAME

      Specifies the username to use when executing the command. This environment variable allows you to specify a default argument for the -u/--username argument on the command line.

      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.

      SEE ALSO

      COUCHBASE-CLI

      Part of the couchbase-cli suite