transparent-huge-pages.txt

====================================
Disable Transparent Huge Pages (THP)
====================================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

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,
because they tend to have sparse rather than contiguous memory access
patterns. You should disable THP on Linux machines to ensure best performance
with MongoDB.

Init Script
-----------

.. important::

   If you are using ``tuned`` or ``ktune`` (for example, if you are running
   Red Hat or CentOS 6+), you must additionally configure them so that THP is
   not re-enabled. See :ref:`configure-thp-tuned`.

.. include:: /includes/steps/disable-thp-in-initd.rst

.. _configure-thp-tuned:

Using ``tuned`` and ``ktune``
-----------------------------

.. important::

   If using ``tuned`` or ``ktune``, you must perform this step in addition
   to installing the init script.

``tuned`` and ``ktune`` are dynamic kernel tuning tools available on Red Hat
and CentOS that can disable transparent huge pages.

To disable transparent huge pages in ``tuned`` or ``ktune``, you need to edit or
create a new profile that sets THP to ``never``.

Red Hat/CentOS 6
~~~~~~~~~~~~~~~~

.. include:: /includes/steps/disable-thp-in-tuned-rhel-6.rst

Red Hat/CentOS 7
~~~~~~~~~~~~~~~~

.. include:: /includes/steps/disable-thp-in-tuned-rhel-7.rst

.. _test-thp-changes:

Test Your Changes
-----------------

You can check the status of THP support by issuing the following commands:

.. code:: sh

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

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

.. code:: sh

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


For both files, the correct output resembles:

.. code:: sh

   always madvise [never]