CouchDB clusters communicate using an Erlang-based mechanism that relies on a shared "secret cookie" for authentication and authorization between nodes.
Let’s see this in action. Imagine you have two CouchDB nodes, couchdb1 and couchdb2, and you want them to form a cluster.
On couchdb1, you might have a local.ini file with the following:
[cluster]
name = my_couchdb_cluster
erlang_cookie = YOUR_SUPER_SECRET_COOKIE_GOES_HERE
And on couchdb2, the local.ini would look identical:
[cluster]
name = my_couchdb_cluster
erlang_cookie = YOUR_SUPER_SECRET_COOKIE_GOES_HERE
When couchdb1 starts, it registers itself with the cluster name my_couchdb_cluster and uses YOUR_SUPER_SECRET_COOKIE_GOES_HERE as its identity. When couchdb2 starts, it does the same. If the cookies match, and the cluster names match, they can then discover and communicate with each other. This cookie is essentially a shared secret that proves to one node that the other node is a legitimate member of the same cluster.
This cookie is the linchpin for Erlang distribution, which is what CouchDB uses under the hood for inter-node communication. Erlang’s distribution protocol requires nodes to authenticate each other before they can send messages. The erlang_cookie setting in local.ini is how CouchDB configures this shared secret. Without matching cookies, nodes will refuse to connect, and your cluster will never form.
The primary problem this solves is preventing unauthorized nodes from joining your CouchDB cluster. Imagine if any server could just join your cluster and start replicating data or querying documents. It would be a massive security hole. The erlang_cookie acts as a pre-shared key, ensuring that only nodes you’ve explicitly configured with the same secret can participate.
Internally, when CouchDB starts, it configures the underlying Erlang virtual machine (VM) with this cookie. The Erlang VM then uses this cookie to encrypt and decrypt authentication challenges sent between nodes. When Node A tries to connect to Node B, Node B will send a challenge. Node A will encrypt it with the cookie and send it back. If Node B can decrypt it successfully using its own copy of the cookie, it knows Node A is legitimate.
The exact levers you control are:
erlang_cookie: This is the shared secret itself. It can be any string of characters. The longer and more random, the more secure.[cluster]section: This section inlocal.iniis where theerlang_cookieresides.- Node Restart: Changing the
erlang_cookierequires a restart of the CouchDB service on all nodes in the cluster to take effect.
A common misconception is that the erlang_cookie is related to CouchDB’s HTTP API authentication. It is not. The erlang_cookie is solely for the inter-node communication mechanism of the Erlang distribution protocol. CouchDB’s HTTP API authentication (username/password or other methods) is entirely separate and operates at a higher layer.
The most surprising true thing about this mechanism is that the cookie isn’t actually transmitted over the network in plain text during the initial handshake. Instead, it’s used to derive session keys for encrypted communication, providing a secure channel for subsequent Erlang RPC calls between nodes.
The next concept you’ll likely encounter is how to manage node discovery and membership within a cluster, especially in dynamic environments.