Upload and Retrieve a Node Certificate

reference

The REST API can be used to upload and retrieve an uploaded node certificate.

Http Methods and URIs

POST /node/controller/reloadCertificate

GET /pools/default/certificate/node/<ip-address-or-domain-name>:8091

Description

The POST method and /node/controller/reloadCertificate URI allow an administrator-configured node certificate to be loaded and reloaded onto its intended node. Prior to loading, the node certificate must have been placed in an appropriately created inbox directory: see Configure Server Certificates, for information.

The GET method and /pools/default/certificate/node/<ip-address-or-domain-name>:8091 URI allow an administrator-configured node certificate to be retrieved. Note that such retrieval can only be performed with an administrator-configured node certificate: it cannot be performed with the default node certificate that is automatically provided to a node by Couchbase Server on initial configuration.

Both calls require the Full Admin, the Local User Security Admin, or the External User Security Admin role.

Curl Syntax

The curl syntax for these calls is as follows:

curl -X POST http://<ip-address-or-domain-name>:8091/node/controller/reloadCertificate
 -u <username>:<password>

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

The copy of the node certificate returned by the GET method should be saved appropriately: for example, by means of > <node-certificate-copy>, on the local filesystem.

Responses

For both the POST and the GET, success returns 200 OK. The GET also returns an object whose fields specify the Subject Common Name, expiry date, and pem-encoded contents of the node certificate. For both, a malformed URI fails, with 404 Object Not Found; failure to authenticate gives 401 Unauthorized; and insufficient privileges gives 403 Forbidden, with a notification such as "Forbidden. User needs one of the following permissions","permissions":["cluster.admin.security!read"]. An incorrectly specified IP address or domain name causes the attempted connection to time out, with a Failed to connect notification.

If the POST is called with either no node certificate or no node-private key in the inbox directory, the call fails with 400 Bad Request, and either the notification "Unable to read private key file /opt/couchbase/var/lib/couchbase/inbox/pkey.key. The file does not exist."; or the notification "Unable to read certificate chain file /opt/couchbase/var/lib/couchbase/inbox/chain.pem. The file does not exist.".

If the GET method is used with no administrator-configured node certificate having been uploaded, the call fails with 404 Object Not Found, and the notification Certificate is not set up on this node.

Examples

The following call uploads an appropriately configured node certificate from the node’s inbox directory:

curl -X POST http://10.143.201.101:8091/node/controller/reloadCertificate \
-u Administrator:password

If successful, the call returns 200 OK.

The following call retrieves the node certificate that is currently uploaded:

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

If successful, the call returns 200 OK, and an object whose fields specify the Subject Common Name, expiry date, and pem-encoded contents of the node certificate:

{
  "subject":"CN=Couchbase Server",
  "expires":"2021-08-24T03:16:32.000Z",
  "pem":"-----BEGIN CERTIFICATE-----
                .
                .
                .
         -----END CERTIFICATE-----\n\n"
}