You are viewing the documentation for a prerelease version.

View Latest

Disabling Transparent Huge Pages (THP)

Transparent huge pages (THP) is a memory management system that is enabled by default in most Linux operating systems. THP must be disabled in order for Couchbase Server to function correctly on Linux.

In Linux operating systems, huge pages is a feature that provides a way for the CPU and OS to create pre-allocated contiguous memory space, and which is designed to improve application performance. Transparent huge pages (THP) is a Linux OS feature that automates the creation of contiguous memory space, and conceals much of the complexity of using actual huge pages on systems with large amounts of memory.

THP is enabled by default in most Linux operating systems, and functions very well for most applications and processes. However, THP is detrimental to Couchbase’s performance (as it is for nearly all databases that tend to have sparse rather than contiguous memory access patterns).

You must disable THP on Linux systems to ensure the optimal performance of Couchbase Server.

Using Init Script

  1. Create the init script.

    vi /etc/init.d/disable-thp

    Add the following contents:

    #!/bin/bash
    ### BEGIN INIT INFO
    # 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, to improve
    #                    Couchbase performance.
    ### END INIT INFO
    
    case $1 in
      start)
        if [ -d /sys/kernel/mm/transparent_hugepage ]; then
          thp_path=/sys/kernel/mm/transparent_hugepage
        elif [ -d /sys/kernel/mm/redhat_transparent_hugepage ]; then
          thp_path=/sys/kernel/mm/redhat_transparent_hugepage
        else
          return 0
        fi
    
        echo 'never' > ${thp_path}/enabled
        echo 'never' > ${thp_path}/defrag
    
        re='^[0-1]+$'
        if [[ $(cat ${thp_path}/khugepaged/defrag) =~ $re ]]
        then
          # RHEL 7
          echo 0  > ${thp_path}/khugepaged/defrag
        else
          # RHEL 6
          echo 'no' > ${thp_path}/khugepaged/defrag
        fi
    
        unset re
        unset thp_path
        ;;
    esac

    Save and close your editor.

  2. Make the script executable.

    sudo chmod 755 /etc/init.d/disable-thp
  3. Configure the OS to run the script on boot.

    • Red Hat, CentOS, & Amazon Linux

    • Ubuntu & Debian

    • SUSE

    sudo chkconfig --add disable-thp
    sudo update-rc.d disable-thp defaults
    sudo insserv /etc/init.d/disable-thp
  4. Override tuned and ktune, if necessary.

    If you are using tuned or ktune (for example, if you are running Red Hat/CentOS 6+) you must also configure them to preserve the above settings after reboot.

  5. Reboot the system and verify that THP is disabled.

If Using tuned and ktune

tuned and ktune are system monitoring and tuning tools available on Red Hat and CentOS. When they are in use on a system, they can be used to enable and disable THP.

To disable THP in tuned and ktune, you need to edit or create a new profile that sets THP to never.

  • Red Hat/CentOS 7

  • Red Hat/CentOS 6

  1. Create a new tuned directory for the new profile.

    sudo mkdir /etc/tuned/no-thp
  2. Create and edit tuned.conf.

    vi /etc/tuned/no-thp/tuned.conf

    Add the following contents:

    [main]
    include=virtual-guest
    
    [vm]
    transparent_hugepages=never

    Save and close your editor.

  3. Enable the new profile.

    sudo tuned-adm profile no-thp
  1. Create a new profile from an existing default profile by copying the relevant directory.

    sudo cp -r /etc/tune-profiles/default /etc/tune-profiles/no-thp

    In the example above, the default profile is the base, and the new profile is no-thp.

  2. Edit ktune.sh.

    vi /etc/tune-profiles/no-thp/ktune.sh

    Add the following line to the start() block of the file, before the return 0 statement:

    set_transparent_hugepages never

    Save and close your editor.

  3. Enable the new profile.

    sudo tuned-adm profile no-thp

Verify THP Status

You can check the THP status by issuing the following commands.

  • Red Hat, CentOS, & Amazon Linux

    cat /sys/kernel/mm/transparent_hugepage/enabled
    cat /sys/kernel/mm/transparent_hugepage/defrag
  • Other Linux Variants

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

If THP is properly disabled, the output of both commands should be the following:

always madvise [never]