Disable Transparent Huge Pages (THP)
On this page
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:
Create the systemd unit file.
Create the following file at /etc/systemd/system/disable-transparent-huge-pages.service:
[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:
/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:
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.
Start the service.
Start the service manually once to ensure that the appropriate THP setting has been changed:
sudo systemctl start disable-transparent-huge-pages
Verify that THP has successfully been set to [never] by running the
following command:
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:
cat /sys/kernel/mm/redhat_transparent_hugepage/enabled
Create the init.d script.
Create the following file 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 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:
echo 'never' | tee ${thp_path}/defrag > /dev/null
Run the script.
Run the script manually once to ensure that the appropriate THP setting has been changed:
sudo /etc/init.d/disable-transparent-hugepages start
Verify that THP has successfully been set to [never] by running the
following command:
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:
cat /sys/kernel/mm/redhat_transparent_hugepage/enabled
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 | | |
SUSE | | |
Red Hat, CentOS, Amazon Linux, and derivatives | |
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.