Some Couchbase deployments require secure communications between nodes across the network, this could be due to reasons like data governance policies or regulatory compliance.  Internet Protocol Security (IPsec) is a protocol suite for secure Internet Protocol (IP) communications by authenticating and encrypting each IP packet of a communication session. IPsec can be used in protecting data flows between a pair of hosts (host-to-host), between a pair of security gateways (network-to-network), or between a security gateway and a host (network-to-host). The goal of this article is to give Couchbase Administrators a quick start on how to configure IPsec across nodes in a Couchbase cluster.  

IPsec Modes

IPSec has two modes: tunnel mode and transport mode. The most widely used is tunnel mode, which is usually used for VPN setups (creating tunnel network device in process). Tunnel mode is not practical for a Couchbase cluster, as it would require creating and maintaining tunnels between all pairs of nodes.

Transport mode is needed when securing communication across nodes in the same network. It allows use of IPsec on a per-packet basis. Completely transparently for applications.

IPSec can provide authentication of packets (i.e. ensure that packets that are received are packets from trusted nodes) and encryption of packets. Transport mode and associated Security Policy Database entries allow setting up behavior required for a Couchbase cluster:

  • specific kinds of incoming packets are only accepted if encapsulated in ipsec and valid (dropped otherwise)

  • specific kinds of outgoing packets are required to be encapsulated in ipsec

Usually “specific kind” is going to be something like: all packets from/to couchbase cluster network segment. Or it can be something like all: all packets to/from couchbase service ports.


  • Linux Distribution (Debian is used for this blog). Windows does support IPsec, this was not tested.

  • Linux Openswan U2.6.32/K2.6.32-573.el6.x86_64 (netkey) or higher
  • Couchbase 4.1 or higher
  • Sudo/root user access to the system

Installation and Configuration of OpenSwan

From the command line using sudo, the following command was run on each node. For other linux distro use your appropriate package manager.

# sudo apt-get update

# sudo apt-get install openswan

The installer may prompt the user to create a x.509 certificate, do not create a x.509 certificate. IPsec needs to configured for transport mode.  In the demonstration environment created for this blog, we have two nodes: and  


1 –       On each node – add a line in the /etc/ipsec.secrets file: ipaddress_node1 ipaddress_node2: PSK “some_key”

2  –     Modify the /etc/ipsec.conf file to use *.conf files located in the ipsec.d subdirectory.  This allows for easy automation if you need to add nodes to the cluster.  Each pair of nodes needs its own entry.  

3  –      Create a configuration file in the /etc/ipsec.d/ directory with the following information:

conn couchbase







  • conn couchbase -connection: arbitrary label for your connection. This can be anything you’d like
  • type=transport: we want to use transport mode for this connectionauthby=secret: we’ll be using a pre-shared key (PSK) for this connection.
  • left= this and the next line are just denoting the IP addresses involved in this IPsec association. It does not matter which IP is “left” and which is “right”.
  • right= see above bullet.
  • pfs=yes: we want to enable Perfect Forward Secrecy for this connection. In short, this drastically improves security. Iauto=start: We want to pro-actively initiate the IPsec association immediately. This can also be set to auto=start, in which case it waits for the other end of the connection to initiate traffic.

4  – Enable IPSec to use the new configuration on both nodes: #sudo service ipsec restart

Testing the setup

From a command line on one node, type the following command:  


From the other node, use the command line and type :  (desired result) If you get no messages, you will need to debug your setup (please refer to IPsec Guides listed below)

#sudo tcpdump esp

Note: ESP = Encapsulating Security Payload

Couchbase Configuration

Install Couchbase on each node, a simple two node configuration. Set up the cluster.  All communication between the two nodes can be traced using the tcpdump esp command, the sample above documents communication between two Couchbase nodes.

Couchbase Test Cluster:

Couchbase Test Cluster

Screenshot – #sudo tcpdump esp


IPsec Overview

Implementating IPsec Transport Mode –

Using StrongSwan (3 node example) –

Sample Configuration Files used for this Test


# /etc/ipsec.conf – Openswan IPsec configuration file


# Manual:     ipsec.conf.5


# Please place your own config files in /etc/ipsec.d/ ending in .conf

version 2.0       # conforms to second version of ipsec.conf specification

# basic configuration

config setup

           # Debug-logging controls:  “none” for (almost) none, “all” for lots.

           # klipsdebug=none

           # plutodebug=”control parsing”

           # For Red Hat Enterprise Linux and Fedora, leave protostack=netkey





           # Enable this if you see “failed to find any available worker”

           # nhelpers=0

#You may put your configuration (.conf) file in the “/etc/ipsec.d/” and uncomment this.

include /etc/ipsec.d/*.conf


include /etc/ipsec.d/*.secrets

# use IP addresses from your own environment PSK “sharedkey”



conn couchbase









Posted by Tim Wong

Tim is a Principal Solutions Consultant at Couchbase supporting accounts in the San Francisco Bay Area. He has worked with database, enterprise data integration (batch, real time, cloud) and business intelligence technologies for over 20 years with stints at Oracle, TIBCO and Informatica.

Leave a reply