Couchbase supports node-to-node encryption or Cluster encryption by adding TLS based encryption to the connections between the nodes within a Couchbase cluster.

When customers using Couchbase require us to comply with privacy regulations such as HIPAA (financial or healthcare customers as an example), then we typically need to allow for Authentication(LDAP), Authorization (RBAC-role based access control), and Encryption. It is also important to support auditing and redaction of important information, especially in logs (Couchbase has support for log redaction using specific tags). When it comes to encryption, Couchbase supports node to node encryption at multiple levels using the cluster configuration level setting. This is controlled by the user and can take 3 values:

  1. Control: At this level, only the cluster and server connections to internal services are encrypted. This basically includes the cluster management information and the related internal processes. However, data across nodes in the cluster is not. So, for example, a server to query service connection is encrypted. This is the default behaviour.

  2. All: At this level, both cross node and inter-service connections are encrypted. What this means is that if there are multiple services on a single node, connections between these services are also encrypted. So along with server connection to the query node, communication between query nodes, from the query node to the indexer node and the FTS node, are also encrypted.

  3. Strict: This is a new level added into our upcoming release 7.0. Setting the cluster encryption level to ‘strict’ is equivalent to setting the cluster encryption level to ‘all’ plus disabling all the non-SSL ports on non-loopback interfaces.

Enabling N-N Encryption

By default, cluster encryption is off. When it is enabled, it is set to Control. It needs to be explicitly set to All if node-to-node encryption is desired. It is supported using Certificates.

  1. Disable auto-failover: Prior to enabling cluster encryption using node-node encryption, auto-failover needs to be disabled by the user in order to prevent nodes in the transition from being labeled unresponsive and failed over. This can be done using the couchbase-cli or REST API.

./couchbase-cli setting-autofailover -c <IP-node1>:8091 -u username -p password 
--enable-auto-failover 0  


curl -u username:password http://<IP-node1>:8091/settings/autoFailover 
-d enabled=false

  1. Enable node to node encryption: Once this returns successfully, we can enable node-to-node encryption using the command:

./couchbase-cli node-to-node-encryption -c <IP-node1>:8091 -u username 
-p password -enable

This sets the cluster encryption level to control and will turn in the encryption for all the nodes in the cluster. We can verify that encryption was successfully enabled using the-getoption above instead of-enable.

  1. Change cluster encryption setting: If the user wishes to change the cluster encryption level, they can use the following CLI command:

    ./couchbase-cli setting-security -c <IP-node1>:8091 -u username -p password 
    -set -cluster-encryption-level all

They can also use the REST API command:

curl -XPOST -u username:password http://<IP-node1>:8091/settings/security 
-d clusterEncryptionLevel=all

  1. Enable auto-failover again: After this, auto-failover needs to be enabled again.

    For more information on enabling and disabling auto-failover, see: To retrieve the cluster-wide encryption settings, see:

Disabling Node-to-node Encryption

  1. Change cluster encryption level to control.

  2. Use node-to-node-encryption setting in the CLI to disable.

Certificates and Node-to-Node Encryption

An important thing to remember when securing the server with X509 certificates is to disable node to node encryption before uploading or rotating the root and intermediate certificates. So if securing a server with the certificates we need to follow these steps:

  1. Disable node to node encryption.

  2. Create root/intermediate certificates and upload or rotate them onto the cluster using the steps outlined in

  3. Re-enable node-to-node-encryption.

One of the limitations of enabling node-to-node encryption is the impact on performance. Since all inter-node communications are encrypted, this does add some overhead. However, the extra secure communication is an added bonus.


With this article, we can see how Couchbase supports node-to-node-encryption and encrypts network traffic between individual nodes and multiple Couchbase services deployed on the nodes in order to optimize security. What this enables us to support are applications that require us to be compliant with privacy regulations such as HIPAA.


Posted by Isha Kandaswamy

Isha Kandaswamy is a Senior Software Engineer at Couchbase. Isha is responsible for the development of designing the different features and tools for the N1QL Query Language -SQL for Json. Also, Designing and implementing features and tools for the N1QL query language.

Leave a reply