DOCS-5330: Tweak THP guide

source/includes/steps-disable-thp-in-initd.yaml

@@ -0,0 +1,83 @@
+title: Create the ``init.d`` script
+stepnum: 1
+ref: create-initd
+action:
+  - pre: |
+      Create the following file at ``/etc/init.d/disable-transparent-hugepages``:
+
+    language: sh
+    code: |
+         #!/bin/sh
+         ### 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' > ${thp_path}/enabled
+             echo 'never' > ${thp_path}/defrag
+
+             unset thp_path
+             ;;
+         esac
+---
+title: Make it executable
+stepnum: 2
+ref: make-executable
+action:
+  - pre: |
+      Run the following command to ensure that the init script can be used:
+
+    language: sh
+    code: sudo chmod 755 /etc/init.d/disable-transparent-hugepages
+---
+title: Configure your operating system to run it on boot
+stepnum: 3
+ref: configure-initd
+action:
+  - pre: |
+      Use the appropriate command to configure the new init script on your Linux
+      distribution.
+
+      .. list-table::
+         :header-rows: 1
+         :widths: 20 80
+
+         * - Distribution
+
+           - Command
+
+         * - Ubuntu and Debian
+
+           - .. code:: sh
+
+                sudo update-rc.d disable-transparent-hugepages defaults
+
+         * - SUSE
+
+           - .. code:: sh
+
+                sudo insserv /etc/init.d/disable-transparent-hugepages
+
+         * - Red Hat, CentOS, Amazon Linux, and derivatives
+
+           - .. code:: sh
+
+                sudo chkconfig --add disable-transparent-hugepages
+...

source/includes/steps-disable-thp-in-tuned-rhel-6.yaml

@@ -0,0 +1,35 @@
+title: Create a new profile
+stepnum: 1
+ref: copy-profile
+action:
+  - pre: |
+      Create a new profile from an existing default
+      profile by copying the relevant directory. In the example we use
+      the ``default`` profile as the base and call our new profile ``no-thp``.
+    language: sh
+    code: |
+      sudo cp -r /etc/tune-profiles/default /etc/tune-profiles/no-thp
+---
+title: Edit ``ktune.sh``
+stepnum: 2
+ref: edit-ktune
+action:
+  - pre: |
+      Edit ``/etc/tune-profiles/no-thp/ktune.sh`` and add the following:
+    language: cfg
+    code: |
+      set_transparent_hugepages never
+    post: |
+      to the ``start()`` block of the file, before the ``return 0``
+      statement.
+---
+title: Enable the new profile
+stepnum: 3
+ref: enable-profile
+action:
+  - pre: |
+      Finally, enable the new profile by issuing:
+    language: sh
+    code: |
+      sudo tune-adm profile no-thp
+...

source/includes/steps-disable-thp-in-tuned-rhel-7.yaml

@@ -0,0 +1,30 @@
+title: Create a new profile
+stepnum: 1
+ref: copy-profile
+action:
+  - pre: |
+      Create a new ``tuned`` profile directory:
+    language: sh
+    code: |
+      sudo mkdir /etc/tuned/no-thp
+---
+title: Edit ``tuned.conf``
+stepnum: 2
+ref: edit-ktune
+action:
+  - pre: |
+      Create and edit ``/etc/tuned/no-thp/tuned.conf`` so that it contains the
+      following:
+    language: ini
+    code: |
+      [main]
+      include=virtual-guest
+
+      [vm]
+      transparent_hugepages=never
+---
+stepnum: 3
+source:
+  file: steps-disable-thp-in-tuned-rhel-6.yaml
+  ref: enable-profile
+...

source/tutorial/transparent-huge-pages.txt

@@ -4,62 +4,66 @@ Disable Transparent Huge Pages (THP)
 
 .. default-domain:: mongodb
 
-Transparent Huge Pages (THP) is a Linux memory management kernel
-module used to reduce the overhead of Translation Lookaside Buffer
-(TLB) lookups on machines with large amounts of memory, and therefore
-a large number of memory pages. In effect, it presents system memory
-as a smaller number of much larger pages rather than as a larger
-number of 4096-byte pages.
+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, THP is known to perform poorly under database workloads,
-which tend to have sparse rather than contiguous memory access
-patterns. You must disable THP on Linux machines used to run MongoDB
-instances to ensure best performance.
+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.
 
-There are three ways to disable Transparent Huge Pages on Linux.
+Init Script
+-----------
 
-In Boot-Time Configuration (Preferred)
---------------------------------------
+.. include:: /includes/steps/disable-thp-in-initd.rst
 
-.. include:: /includes/steps/disable-thp-in-grub.rst
+Using ``tuned`` and ``ktune``
+-----------------------------
 
-Using ``tuned`` and ``ktune`` (Necessary if you use ``tuned``)
---------------------------------------------------------------
+.. important::
 
-``tuned`` and ``ktune`` are dynamic kernel tuning tools that act in
-accordance with policies set by the system administrator. One of the
-settings available to ``tuned`` and ``ktune`` is whether or not to use
-THP.
+   If installed, you must configure ``tuned`` and ``ktune`` to prevent them from
+   re-enabling THP.
 
-To disable transparent hugepages, you need to edit or create a new
-profile that sets THP to ``never``.
+``tuned`` and ``ktune`` are dynamic kernel tuning tools available on Red Hat
+and CentOS that can disable transparent huge pages.
 
-.. include:: /includes/steps/disable-thp-in-ktune.rst
+To disable transparent huge pages in ``tuned`` or ``ktune``, you need to edit or
+create a new profile that sets THP to ``never``.
 
-In ``/etc/rc.local`` (Alternate)
---------------------------------
+Red Hat/CentOS 6
+~~~~~~~~~~~~~~~~
 
-.. include:: /includes/steps/disable-thp-in-rc.local.rst
+.. 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
 -----------------
 
-Whichever of the three methods you use, you can check the status of THP support by issuing the command:
+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
 
-or
+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
 
-on Red Hat Enterprise Linux, CentOS, and potentially other Red
-Hat-based derivatives.
 
-Correct output resembles:
+For both files, the correct output resembles:
 
 .. code:: sh