• Administration >
• MongoDB Performance >
• Disable Transparent Huge Pages (THP)

Disable Transparent Huge Pages (THP)

Transparent Huge Pages (THP) is a Linux memory management system that reduces the overhead of Translation Lookaside Buffer (TLB) lookups on machines with large amounts of memory by using larger memory pages.

However, database workloads often perform poorly with THP enabled, because they tend to have sparse rather than contiguous memory access patterns. When running MongoDB on Linux, THP should be disabled for best performance.

To ensure that THP is disabled before mongod starts, you should create a service file for your platform’s initialization system that disables THP at boot. Instructions are provided below for both the systemd and the System V init initialization systems.

Additionally, for RHEL / CentOS systems that make use of ktune and tuned performance profiles, you must create a custom tuned profile as well.

Create a Service File

To create a service file that disables THP, you will use the built-in initialization system for your platform. Recent versions of Linux tend to use systemd (which uses the systemctl command), while older versions of Linux tend to use System V init (which uses the service command). Refer to the documentation for your operating system for more information.

Use the initialization system appropriate for your platform:

• systemd (systemctl)
• System V Init (service)

1

Create the systemd unit file.

Create the following file at /etc/systemd/system/disable-transparent-huge-pages.service:

copy

[Unit]
Description=Disable Transparent Huge Pages (THP)
DefaultDependencies=no
After=sysinit.target local-fs.target
Before=mongod.service

[Service]
Type=oneshot
ExecStart=/bin/sh -c 'echo never | tee /sys/kernel/mm/transparent_hugepage/enabled > /dev/null'

[Install]
WantedBy=basic.target

Note

Some versions of Red Hat Enterprise Linux, and potentially other Red Hat-based derivatives, use a different path for the THP enabled file:

copy

/sys/kernel/mm/redhat_transparent_hugepage/enabled

Check to see which path is in use on your system, and update the disable-transparent-huge-pages.service file accordingly.

Note

Prior to version 4.2, MongoDB also checks the THP defrag setting and presents a startup warning if defrag is enabled. As long as THP itself is disabled in the systemd unit file, MongoDB is unaffected by the defrag setting. However, to avoid this message, you may set defrag to never by adding the following additional line to the systemd unit file, just after the existing ExecStart statement:

copy

ExecStart=/bin/sh -c 'echo never | tee /sys/kernel/mm/transparent_hugepage/defrag > /dev/null'

If on Red Hat or similar, the path to the defrag file might be different. See the note above for more details, and and update the disable-transparent-huge-pages.service file accordingly.

2

Reload systemd unit files.

Run the following command to reload systemd unit files to make disable-transparent-huge-pages.service available for use:

copy

sudo systemctl daemon-reload

3

Start the service.

Start the service manually once to ensure that the appropriate THP setting has been changed:

copy

sudo systemctl start disable-transparent-huge-pages

Verify that THP has successfully been set to [never] by running the following command:

copy

cat /sys/kernel/mm/transparent_hugepage/enabled

On Red Hat Enterprise Linux and potentially other Red Hat-based derivatives, you may instead need to use the following:

copy

cat /sys/kernel/mm/redhat_transparent_hugepage/enabled

4

Configure your operating system to run it on boot.

To ensure that this setting is applied each time your system boots, run the following command:

copy

sudo systemctl enable disable-transparent-huge-pages

5

Customize tuned / ktune profile, if applicable.

If you are using tuned or ktune on RHEL/ CentOS, you must now also create a custom tuned profile.

1

Create the init.d script.

Create the following file at /etc/init.d/disable-transparent-hugepages:

copy

#!/bin/bash
### BEGIN INIT INFO
# Provides:          disable-transparent-hugepages
# Required-Start:    $local_fs
# Required-Stop:
# X-Start-Before:    mongod mongodb-mms-automation-agent
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Disable Linux transparent huge pages
# Description:       Disable Linux transparent huge pages, to improve
#                    database 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' | tee ${thp_path}/enabled > /dev/null

    unset thp_path
    ;;
esac

Note

Prior to version 4.2, MongoDB also checks the THP defrag setting and presents a startup warning if defrag is enabled. As long as THP itself is disabled in the init.d script, MongoDB is unaffected by the defrag setting. However, to avoid this message, you may set defrag to never by adding the following line to the init.d script, just before the unset thp_path statement:

copy

echo 'never' | tee ${thp_path}/defrag > /dev/null

2

Make it executable.

Run the following command to make the script executable:

copy

sudo chmod 755 /etc/init.d/disable-transparent-hugepages

3

Run the script.

Run the script manually once to ensure that the appropriate THP setting has been changed:

copy

sudo /etc/init.d/disable-transparent-hugepages start

Verify that THP has successfully been set to [never] by running the following command:

copy

cat /sys/kernel/mm/transparent_hugepage/enabled

On Red Hat Enterprise Linux and potentially other Red Hat-based derivatives, you may instead need to use the following:

copy

cat /sys/kernel/mm/redhat_transparent_hugepage/enabled

4

Configure your operating system to run it on boot.

To ensure that this setting is applied each time your system boots, run the following command for your Linux distribution:

Distribution	Command
Ubuntu and Debian	sudo update-rc.d disable-transparent-hugepages defaults
SUSE	sudo insserv /etc/init.d/disable-transparent-hugepages
Red Hat, CentOS, Amazon Linux, and derivatives	sudo chkconfig --add disable-transparent-hugepages

5

Customize tuned / ktune profile, if applicable.

If you are using tuned or ktune on RHEL/ CentOS, you must now also create a custom tuned profile.

Using tuned and ktune

Important

If using tuned or ktune, you must also perform the steps in this section after creating the service file above.

tuned and ktune are dynamic kernel tuning tools that can affect the transparent huge pages setting on your system. If you are using tuned / ktune on your RHEL / CentOS system while running mongod, you must create a custom tuned profile to ensure that THP remains disabled.

Red Hat/CentOS 6

1

Create a new profile.

Create a new profile from an existing profile by copying the relevant directory. This example uses the virtual-guest profile as the base, and uses virtual-guest-no-thp as the new profile:

copy

sudo cp -r /etc/tune-profiles/virtual-guest /etc/tune-profiles/virtual-guest-no-thp

2

Edit ktune.sh.

Edit /etc/tune-profiles/virtual-guest-no-thp/ktune.sh and change the set_transparent_hugepages setting to the following:

copy

set_transparent_hugepages never

3

Enable the new profile.

Enable the new profile:

copy

sudo tuned-adm profile virtual-guest-no-thp

Red Hat/CentOS 7 and 8

1

Create a new profile.

Create a new directory to hold the custom tuned profile. This example inherits from the existing virtual-guest profile, and uses virtual-guest-no-thp as the new profile:

copy

sudo mkdir /etc/tuned/virtual-guest-no-thp

2

Edit tuned.conf.

Create and edit /etc/tuned/virtual-guest-no-thp/tuned.conf so that it contains the following:

copy

[main]
include=virtual-guest

[vm]
transparent_hugepages=never

This example inherits from the existing virtual-guest profile. Select the profile most appropriate for your system.

5

Enable the new profile.

Enable the new profile:

copy

sudo tuned-adm profile virtual-guest-no-thp

←   Database Profiler Output UNIX ulimit Settings  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.