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:

      # 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
          if [ -d /sys/kernel/mm/transparent_hugepage ]; then
          elif [ -d /sys/kernel/mm/redhat_transparent_hugepage ]; then
            return 0
          echo 'never' > ${thp_path}/enabled
          echo 'never' > ${thp_path}/defrag
          if [[ $(cat ${thp_path}/khugepaged/defrag) =~ $re ]]
            # RHEL 7
            echo 0  > ${thp_path}/khugepaged/defrag
            # RHEL 6
            echo 'no' > ${thp_path}/khugepaged/defrag
          unset re
          unset thp_path

      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:


      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]