A newer version of this documentation is available.

View Latest


      Couchbase Server handles client-to-cluster, node-to-node, and cluster-to-cluster communications. It also provides connectivity to a number of third-party products.

      Communication Summary

      The network-communication options supported by Couchbase Server are as follows:

      • Client-to-Cluster. Client applications communicate with a Couchbase Server-cluster through a set of server-defined access-points, each of which provides ports for both clear and encrypted communication. For detailed information, see Couchbase Server Ports.

      • Node-to-Node. Cluster-nodes intercommunicate in order to replicate data, maintain indexes, check the health of nodes, communicate changes to the cluster-configuration, and more. See Cluster Manager, for detailed information. For information on how to encrypt the communications between nodes, see Node-to-Node Encryption.

      • Cluster-to-Cluster. Couchbase Server-clusters communicate with one another by means of Cross Data Center Replication. See Cross Data Center Replication (XDCR), for detailed information.

      • Cluster-to-Connector. Couchbase Server-clusters communicate with third party products; by means of connectors. Connectors are provided for Elasticsearch, Hadoop, Kafka, Spark, and Talend. Drivers are provided for ODBC and JDBC. See Connector Guides, for detailed information.

      Connectivity Phases

      Client connectivity is established in three phases: Authentication and Authorization, Discovery, and Service Connection.

      1. Authentication and Authorization: The client authenticates with username and password. If these are associated with a Couchbase-Server defined role, itself associated with appropriate privileges on the resource access to which is being requested, the client is authorized, and access is granted. Otherwise, access is denied. See Authorization for details.

      2. Discovery: A cluster-map is returned to the client. This indicates the current cluster-topology; including the list of nodes, the data-distribution across the nodes, and the service-distribution across the nodes.

      3. Service Connection: Once in possession of the cluster-map, the client determines the connections needed to establish and perform service-level operations. Additional authorizations may be required, depending on the operations being attempted. Note that in the event of topology-changes, a service connection-request may result in an exception; in which case discovery must be re-run, and operations retried with new connections.

      Managing IP-Address Families

      Couchbase Server supports both the IPv4 and IPv6 address families. The address family can be established as part of a cluster’s initial configuration: see Create a Cluster and Initialize a Node with the CLI, for details on how to do this with the UI and CLI respectively.

      For information on using the CLI to change the address family for an existing cluster, see Manage Address Families.

      Services and IP-Address Families

      All Couchbase Services bind on all their assigned ports with the same address family — either IPv4 or IPv6, depending on which address family has been established for the cluster; either at initial configuration, or subsequently by means of the CLI. If a service cannot bind on all its assigned ports with the established address family, the service does not start. For more information, see Couchbase Server Ports.

      Alternate Addresses

      Couchbase Server allows an alternate address to be assigned to any individual cluster-node, and an alternate port number to be assigned to any service running on that node. For a list of services, and the standard ports they occupy, see Couchbase Server Ports.

      When assigning an alternate address and using different port numbers than the expected, port forwarding must be enabled on the host machine. For example, on a virtual machine:

      iptables -A PREROUTING -t nat -i eth0 -p tcp --dport 9000 -j REDIRECT --to-port 8093

      This command will create a redirection from the external port 9000 to the query service running on port 8093.

      The assigning of alternate addresses and port numbers, which can be accomplished by means of the CLI and the REST API, may facilitate communication with external applications that are not permitted to contact a cluster’s nodes directly; but have access to a router or other networked entity that provides externally visible addresses on the nodes’ behalf. Note that an alternate address can be used to specify an XDCR target cluster: see Create a Reference.

      Two possible use cases are given below.

      Internal Network or Cloud Access

      Access to nodes within an internal network or cloud is shown by the following illustration:


      The annotations to this diagram are as follows:

      1. Within an internal network or cloud environment, two nodes are accessible by means of their principal IP addresses, which are and

      2. Each node is configured with an alternate address. This is not validated by the node on which it is configured: the operating system for the node is in most cases unaware of the external address. The router typically makes the alternate address available to the Network Address Translation (NAT) facility for the network; after which it is used as the external address for the node. Thus, it can be referenced by external applications.

      3. A publicly available DNS server lists the alternate addresses for the nodes.

      4. An external application resolves the domain name for each node to its corresponding alternate address.

      5. The external application contacts the NAT by means of the alternate addresses. The NAT translates the alternate address to the internal, and communication between the nodes and the external application continues on that basis.

      Dual Network

      Applications' access to nodes can be segregated, by means of a Dual Network, in order to optimize security. This is shown by the following illustration:


      The annotations to this diagram are as follows:

      1. A cluster can be accessed by its principal address,, or its alternate, Within the cluster are two nodes, each of which can be accessed internally by means of a primary or secondary IP address.

      2. The path to the cluster by which application-requests are routed may depend on whether the cluster’s principal or alternate address is used.

      3. When in possession of both principal and alternate addresses, applications generally default to use of the principal; but may be able to override the default, and use the alternate. Here indeed, Application 2 uses the alternate.

      4. Within the cluster, node-access by external applications is managed according to the mappings for the cluster’s principal and alternate addresses. Here, the principal address is mapped to the nodes’ primary addresses, and the alternate address is mapped to the nodes’ secondary addresses.

      Assigning Alternate Addresses

      Couchbase Server allows alternate addresses to be assigned by means of: