You are viewing the documentation for a prerelease version.

View Latest

Node-to-Node Encryption

Network traffic between the individual nodes of a Couchbase-Server cluster can be encrypted, in order to optimize cluster-internal security.

Node-to-Node Encryption

Couchbase Server supports node-to-node encryption, whereby network traffic between the individual nodes of a cluster is encrypted, in order to optimize cluster-internal security.

Node-to-node encryption can be established on either of two levels:

  • Control. Cluster-management information passed between nodes by the Cluster Manager and related low-level processes is encrypted. However, the data that is passed between nodes by Couchbase Services continues to be passed in the clear. When node-to-node encryption is first enabled, this is the default.

  • All. Both cluster-management information and data is passed in encrypted form. Node-to-node encryption can be supported by means of either the self-signed certificates with which nodes are protected by default; or certificates signed by a recognized Certificate Authority, and installed by the administrator.

For practical steps towards set-up, see Apply Node-to-Node Encryption.

Managing IP-Address Families

Node-to-node encryption supports both the IPV4 and IPV6 address-families. The Couchbase CLI allows selection of the family to be used for the cluster. The following requirements apply:

  • Each cluster-node must be named with a fully qualified domain-name (such as

  • Each cluster-node must be operating in dual stack mode, thereby supporting both IPV4 and IPV6 addressing.

DNS records must have been updated to resolve to the appropriate addresses.

Using Node-to-Node Encryption

Node-to-node encryption is disabled by default. Note that auto-failover must be switched off both for a change to be made to the cluster’s address-family, and for encryption to be enabled or disabled: auto-failover can be switched back on after the necessary changes have been made. (This requirement prevents nodes that are undergoing changes from being determined unresponsive during the process, and unnecessarily failed over.)

Node-to-node encryption is managed by means of the Couchbase CLI. The typical command-sequence is summarized below.

  1. Change address family. Both IPV4 and IPV6 addresses are supported: one or the other must be selected. The selected setting is applied to every node in the cluster.

    Note that in order to change the address family, auto-failover must first be disabled, since each per-node address-family change potentially results in the node appearing offline, and so getting unnecessarily failed over. Auto-failover can be re-enabled following completion of encryption-configuration

    The address family is changed by means of the ip-family CLI command.

  2. Enable cluster encryption. Cluster encryption must be specifically enabled: by default, it is disabled. To enable or disable cluster encryption, or to determine the current setting, use the node-to-node-encryption CLI command.

  3. Establish cluster encryption-level. This determines whether only cluster-management information or both cluster-management information and data will be passed in encrypted form: this are respectively the control and all encryption levels. Use the setting-security CLI command to specify or to get the current setting.

  4. If required, re-enable auto-failover.

For a more detailed account of this sequence, see Apply Node-to-Node Encryption.

Certificate Rotation and Node-to-Node Encryption

Typically, the certificates used to protect and authenticate a cluster should be rotated. Before this operation is performed, node-to-node encryption should be disabled; and following the operation, re-enabled, as follows:

  1. Use node-to-node-encryption, to disable node-to-node encryption. Note that node-to-node encryption cannot be disabled when the encryption-level has been specified as all. Before attempting to disable, determine the encryption-level, and if necessary, change it to control.

  2. Rotate certificates, using ssl-manage.

  3. Re-enable node-to-node encryption, using node-to-node-encryption, and establish the appropriate level of encryption.