A newer version of this documentation is available.

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.

      In Couchbase Server Version 7.0.2 and later, node-to-node encryption is supported for all Couchbase services. Note however, that in versions 7.0 and 7.0.1, node-to-node encryption is not supported for the Eventing Service.

      Node-to-node encryption can be established on the following 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 Couchbase-provided certificates with which nodes are protected by default; or certificates installed by the administrator.

      • Strict — available only in Couchbase Server Version 7.0.2 and later. This means All with only encrypted communication permitted between nodes and between the cluster and external clients. Note, however, that after Strict has been specified, communication that occurs entirely on a single node using the loopback interface (whereby the machine is identified as either ::1 or is still permitted in non-encrypted form.

        Applying Strict as the clusterEncryptionLevel has a number of significant consequences, which should be fully understood before proceeding. See Enforcing TLS.

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

      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.)

      Note also that on all 7.0+ versions of Couchbase Server, Eventing functions must be paused before node-to-node encryption for the cluster is enabled, disabled, or is established at a new level: this prevents loss of mutations. All paused Eventing functions should then be resumed, once changes to node-to-node encryption are complete. For information, see eventing-function-setup.

      Node-to-node encryption is managed by means of the Couchbase CLI. The typical sequence of commands and other activities 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. The address family is changed by means of the ip-family CLI command.

      2. Pause all Eventing functions.

      3. 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.

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

      5. Resume all previously paused Eventing functions.

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

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

      Certificate Management and Node-to-Node Encryption

      Before the root or intermediate certificates for a cluster are either uploaded for the first time, or are subsequently rotated, node-to-node encryption should be disabled:

      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. Create or rotate the root and/or intermediate certificates as appropriate: see the procedures in Configure Server Certificates. Also see ssl-manage.

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

      Note that the node certificates for a cluster can be created or rotated without node-to-node-encryption being disabled.