A newer version of this documentation is available.

View Latest

Swap Space and Kernel Swappiness

    On Linux, swappiness indicates how frequently the system uses the swap space based on its RAM usage.

    Couchbase Server efficiently uses available RAM for your working set data; ideally, sufficient RAM remains available to the operating system even with your cluster’s configured Server RAM Quota as well. It is always a good idea to configure a reasonable amount of virtual memory or swap space on Linux-based nodes and a Pagefile on Windows. Sufficient virtual memory avoids that Couchbase Server processes from being killed by the OS, such as the Linux out of memory (OOM) killer.

    The Linux kernel swappiness setting defines how aggressively the kernel will swap memory pages versus dropping pages from the page cache. A higher value increases swap aggressiveness while a lower value reduces swapping. The swappiness range is from 0 to 100, and most Linux distributions have swappiness set to 60 by default.

    Set the swappiness setting to 0 (zero) or at most 1 for optimal Couchbase Server operation. The low range tells the kernel to swap as little as possible to disk and favor RAM. Couchbase Server is optimized with its managed cache to use RAM and is capable of managing what should be in RAM and what should not be. By allowing the OS to control what memory pages are in RAM, you lower Couchbase Server’s effectiveness.

    Changing Swappiness

    Swappiness levels tell the virtual memory subsystem how much it should attempt to swap to disk. The OS will try to swap out items in memory even when there is plenty of RAM available. The OS default value for swappiness is usually 60, which is too high.

    1. To see at what value is your OS set, run the following command:

      $ cat /proc/sys/vm/swappiness
    2. As Couchbase Server is a memory-first architecture, performance is gained (or at minimum not lost) just by changing the swappiness value to 0.

      There are debates on many Linux forums about the merits of using either 0 or 1, but it is recommended to do your own research.

      The swappiness value tells to the OS’s virtual memory subsystem not swap items from RAM to disk unless it really has to. If the cluster nodes are sized correctly, swapping should not be necessary.

      To change the swappiness setting, use sudo or just become root:

      # Set the value for the running system
           sudo sh -c 'echo 0 > /proc/sys/vm/swappiness'
           # Backup sysctl.conf
           sudo cp -p /etc/sysctl.conf /etc/sysctl.conf.`date +%Y%m%d-%H:%M`
           # Set the value in /etc/sysctl.conf so it stays after reboot.
           sudo sh -c 'echo "" >> /etc/sysctl.conf'
           sudo sh -c 'echo "#Set swappiness to 0 to avoid swapping" >> /etc/sysctl.conf'
           sudo sh -c 'echo "vm.swappiness = 0" >> /etc/sysctl.conf'
    3. Make sure to modify any continuous deployment process that build OS to do this as well. This is especially critical for public/private clouds where it is so easy to bring up new instances. This needs to be part of the build process for any new Couchbase node.

    If you are making a golden master OS image or use a configuration automation system, do not forget to make this permanent change there too.
    On Windows, there are no recommended virtual memory optimizations.