A newer version of this documentation is available.

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 7+) 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

      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

      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]