Upload and Retrieve the Root Certificate

reference

The REST API can be used to upload and retrieve the cluster’s root certificate. It can also be used to retrieve information on the cluster, by referencing a copy of the root certificate.

Http Methods and URIs

POST /controller/uploadClusterCA

GET /pools/default/certificate

GET /pools/default

Description

The POST method and /controller/uploadClusterCA URI upload an appropriately configured certificate to the cluster, so that it becomes the root certificate for the cluster. The Full Admin, the Local User Security Admin, or the External User Security Admin role is required. The certificate must be specified as binary data, in a location on the filesystem, for successful upload to occur.

The GET method and /pools/default/certificate URI make a copy of the cluster’s current root certificate, and returns the copy. This call is authorized for all Couchbase Server roles.

The GET method and /pools/default URI return an object containing cluster information

Curl Syntax

The curl syntax for each call is as follows:

curl -X POST
  --data-binary "@./ca.pem"
  http://<ip-address-or-host-name>:8091/controller/uploadClusterCA
  -u <username>:<password>

curl -X GET
  http://<ip-address-or-domain-name>:8091/pools/default/certificate
  -u <username>:<password>

curl -X GET
  https://<ip-address-or-domain-name>:18091/pools/default
  --cacert <copy-of-current-root-certificate>
  -u <username>:<password>

The certificate specified for upload to the POST method must be an appropriately configured binary, accessible by means of the given path. The certificate must be named ca.pem.

The certificate-copy returned by the GET method and /pools/default/certificate URI should be appropriately saved: for example, with > <certificate-copy-name>, on the local filesystem. Note that if the URI is extended to /pools/default/certificate?extended=true, an object is returned, rather than the raw, pem-encoded certificate-content alone. This object contains the following fields:

type: Whether the certificate was generated by Couchbase Server, or was uploaded by an administrator.
pem: The pem-encoded certificate-content.
subject: the Subject Common Name of the certificate.
expires: Expiration data.
warnings: Warnings, if appropriate.

The argument to the cacert flag used by GET /pools/default must be a copy of the current root certificate for the current cluster. If the current node is specified, the ip-address-or-domain-name can be the loopback IP address, 127.0.0.1. An object containing information on the current cluster is returned and displayed.

Note that GET /pools/default must employ secure access to Couchbase Server, via the secure port 18091.

Responses

For the POST method, success gives 200 OK, and returns the readable text of the uploaded certificate. Additionally, warnings may be displayed — for example, if the root certificate is uploaded (as may be expected) prior to the uploading of corresponding node certificates (whereby the current node certificates have not been signed by the new root), the warning may be as follows: [{"node":"ns_1@127.0.0.1","message":"Certificate is not signed with cluster CA."}]. Failure to authenticate gives 401 Unauthorized. An incorrectly specified URI fails with 404 Object Not Found. Failure to specify an appropriately configured certificate fails with 400 Bad Request and the notification {"error":"Malformed certificate"} (the message Couldn’t read data from file may also be displayed). An incorrectly specified IP address or domain name causes the attempted connection to time out, with a Failed to connect notification.

For the GET method and /pools/default/certificate URI, success gives 200 OK, and returns the readable text of the uploaded certificate. Failure to authenticate gives 401 Unauthorized. A malformed URI fails, with 404 Object Not Found. An incorrectly specified IP address or domain name causes the attempted connection to time out, with a Failed to connect notification.

For the GET method and /pools/default URI, success gives 200 OK, and displays an object containing information on the current cluster. Failure to authenticate gives 401 Unauthorized. A malformed URI fails, with 404 Object Not Found. An incorrectly specified IP address or domain name causes the attempted connection to time out, with a Failed to connect notification.

Examples

The following example uploads an appropriately configured root certificate:

curl -v -X POST http://10.143.201.101:8091/controller/uploadClusterCA \
--data-binary "@./ca.pem" \
-u Administrator:password

If successful, the call returns 200 OK, and displays the following output:

{"cert":{"type":"uploaded","pem":"-----BEGIN CERTIFICATE-----\nMIIDCzCCAfOgAwIBAgIJ
    .
    .
    .
AH\n-----END CERTIFICATE-----\n","subject":"CN=Couchbase Root CA","expires":"2030-08 22T03:14:49.000Z"},"warnings":[{"node":"ns_1@127.0.0.1","message":"Certificate is not
signed with cluster CA."}]}

The output thus displays in readable form the body of the new root certificate (shown here in truncated form). It also provides, in this case, a warning: indicating that the node certificate for the node is not yet one signed by the new root certificate. This can be remedied by uploadoing an appropriately signed, new node certificate.

The following example retrieves the current root certificate:

curl -v -X GET http://10.143.201.101:8091/pools/default/certificate \
-u Administrator:password > cert-copy

If successful, this returns 200 OK, with a copy of the current root certificate. This can be inspected at the command line, with a tool such as more.

Once retrieved, a root certificate can be used with either the curl or the wget command, to return information on the current cluster. The following example shows how to use curl in this way. The file cert-copy is a copy of the root certificate, already retrieved by means of GET /pools/default/certificate:

curl -v -X GET https://127.0.0.1:18091/pools/default \
--cacert ./cert-copy \
-u Administrator:password

If successful, the call returns 200 OK and displays an object containing cluster information. The initial sections of this object, appropriately formatted, may appear as follows:

{
  "name": "default",
  "nodes": [
    {
      "systemStats": {
        "cpu_utilization_rate": 17.97752808988764,
        "cpu_stolen_rate": 0,
        "swap_total": 536866816,
        "swap_used": 536842240,
        "mem_total": 1040723968,
        "mem_free": 60387328,
        "mem_limit": 1040723968,
        "cpu_cores_available": 1,
        "allocstall": 38930
      },
      "interestingStats": {
        "cmd_get": 0,
        "couch_docs_actual_disk_size": 64626447,
        "couch_docs_data_size": 42551296,
        "couch_spatial_data_size": 0,
        "couch_spatial_disk_size": 0,
        "couch_views_actual_disk_size": 974397,
        "couch_views_data_size": 970245,
        "curr_items": 38894,
        "curr_items_tot": 38894,
        "ep_bg_fetched": 0,
        "get_hits": 0,
        "mem_used": 84958992,
        "ops": 0,
        "vb_active_num_non_resident": 0,
        "vb_replica_curr_items": 0
      },
      "uptime": "179052",
      "memoryTotal": 1040723968,
      "memoryFree": 60387328,
            .
            .
            .

The command wget can be similarly used, as follows:

wget --ca-certificate ./cert-copy \
https://127.0.0.1:18091/pools/default -O output \
--user Administrator --password password

Note that wget here uses the secure port 18091. The returned object is written to the file output.