Docs Menu
Docs Home
/
MongoDB Manual
/ / /

Disable Transparent Huge Pages (THP)

On this page

  • Create a Service File
  • Using tuned and ktune

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.

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:

1

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

[Unit]
Description=Disable Transparent Hugepages (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 && echo never | tee /sys/kernel/mm/transparent_hugepage/defrag > /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:

/sys/kernel/mm/redhat_transparent_hugepage/enabled

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

2

To reload the systemd unit files and make disable-transparent-huge-pages.service available for use, run the following command :

sudo systemctl daemon-reload
3

Run:

sudo systemctl start disable-transparent-huge-pages

To verify that the relevant THP settings have changed, run the following command:

cat /sys/kernel/mm/transparent_hugepage/disabled && cat /sys/kernel/mm/transparent_hugepage/defrag

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

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

The output should resemble the following:

never
never
4

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

sudo systemctl enable disable-transparent-huge-pages
5

If you use tuned or ktune profiles on RHEL/ CentOS, you must also create a custom tuned profile.

1

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

#!/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 Hugepages
# Description: Disable Linux Transparent Hugepages, 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 /sys/kernel/mm/transparent_hugepage/enabled > /dev/null && echo 'never' | tee /sys/kernel/mm/transparent_hugepage/defrag > /dev/null
unset thp_path
;;
esac
2

Run:

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

Run:

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

To verify that the relevant THP settings have changed, run the following command:

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

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

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

The output should resemble the following:

never
never
4

To ensure that this setting is applied each time the operating sytem starts, 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

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

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.

1

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:

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

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

set_transparent_hugepages never
3

Enable the new profile:

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

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:

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

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

[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.

3

Enable the new profile:

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

Back

Performance