A newer version of this documentation is available.

View Latest

Disabling Transparent Huge Pages (THP)

    The Transparent Huge Pages (THP) feature of the Linux kernel must be disabled on systems running Couchbase Server.

    Huge Pages in Linux-based operating systems create pre-allocated contiguous memory space designed to assist application performance.

    Transparent Huge Pages (THP) is a Linux OS feature that conceals much of the complexity of using actual Huge Pages as well as automates the creation of contiguous memory space. It is enabled by default in some Linux Operating systems, but not all.

    For most workloads it functions very well, but for databases such as Couchbase it does not. Not only is it not recommended by the OS vendors for databases, but it is detrimental to the performance and function of Couchbase cluster nodes. Such negative influence on the performance is not unique to Couchbase but applies almost to all databases that usually need sparse memory access patterns and rarely have contiguous access patterns.

    Turning THP off and keeping it off after reboot is not entirely supported by the Linux OS, and you will have to establish a process that is easy to perform and repeat.

    To disable THP follow these steps:

    Check the THP status

    Check the status of THP by issuing the following commands:

    cat /sys/kernel/mm/transparent_hugepage/enabled
    cat /sys/kernel/mm/transparent_hugepage/defrag

    On some Red Hat and Red Hat variants, you might have to do this:

    cat /sys/kernel/mm/redhat_transparent_hugepage/enabled
    cat /sys/kernel/mm/redhat_transparent_hugepage/defrag

    Continue with the procedure described below if in one or both files the output looks as follows:

    [always] madvise never
    Copy the init script

    The init script is designed to make sure that the changes are made around the same time as Couchbase Server is loaded on reboot.

    # Provides:          disable-thp
    # Required-Start:    $local_fs
    # Required-Stop:
    # X-Start-Before:    couchbase-server
    # Default-Start:     2 3 4 5
    # Default-Stop:      0 1 6
    # Short-Description: Disable THP
    # Description:       disables Transparent Huge Pages (THP) on boot
    case $1 in
      if [ -d /sys/kernel/mm/transparent_hugepage ]; then
        echo 'never' > /sys/kernel/mm/transparent_hugepage/enabled
        echo 'never' > /sys/kernel/mm/transparent_hugepage/defrag
      elif [ -d /sys/kernel/mm/redhat_transparent_hugepage ]; then
        echo 'never' > /sys/kernel/mm/redhat_transparent_hugepage/enabled
        echo 'never' > /sys/kernel/mm/redhat_transparent_hugepage/defrag
        return 0
    Register the code in the OS

    As root do the following:

    1. Create a file with the above code:

      $ sudo vi /etc/init.d/disable-thp
    2. Chmod the file to be executable:

      $ sudo chmod 755 /etc/init.d/disable-thp
    3. Execute it so it takes effect right now:

      $ sudo service disable-thp start
    Make sure the Init script starts at boot

    For Red Hat variants:

    $ sudo chkconfig disable-thp on

    For Ubuntu:

    $ sudo update-rc.d disable-thp defaults
    Test the process

    Check the status of THP by issuing the following commands:

    cat /sys/kernel/mm/transparent_hugepage/enabled
    cat /sys/kernel/mm/transparent_hugepage/defrag

    On some Red Hat or Red Hat variants, you might have to do this instead:

    cat /sys/kernel/mm/redhat_transparent_hugepage/enabled
    cat /sys/kernel/mm/redhat_transparent_hugepage/defrag

    For both files, the output should be like this:

    always madvise [never]