Disabling Transparent HugePage (THP)

For NuoDB 5.0.1 or later and RHEL 8 or later, it is not required to disable the host machine’s kernel THP settings. NuoDB will disable THP for NuoDB database processes if THP is configured to always at the OS level. The content on this page provides information and instruction for running NuoDB if you plan to manually disable THP.

Transparent HugePage (THP) is a Linux feature that reduces the overhead of using large amounts of memory. Like other databases, NuoDB uses memory in such a way that enabling THP results in a slow but steady increase in Resident Set Size (RSS). This decreases the performance of NuoDB Transaction Engines (TEs) and Storage Managers (SMs) to a point where the system eventually runs out of memory and kills those processes using significant amounts of memory.

If you install NuoDB on a system where THP is enabled, NuoDB TE and SM processes will not start.

If you see an error such as NuoDB will not run with transparent hugepages enabled when trying to start a NuoDB SM or TE, this system has THP enabled and this must be addressed.

Determining Whether THP is Enabled

To determine the current state of THP on a system, run the following command:

cat /sys/kernel/mm/transparent_hugepage/enabled

The current setting for THP will be the value enclosed in square brackets. If the square brackets surround [madvise] or [never], then THP has the correct setting for NuoDB. If the square brackets surround [always], as shown below, THP is enabled and you must take action to disable it to run NuoDB.

cat /sys/kernel/mm/transparent_hugepage/enabled
[always] madvise never

Disabling THP

For information on disabling THP, see the following sections:

Disabling THP Until the Next Restart

To disable THP until the next system restart, run the following commands:

echo madvise | sudo tee -a /sys/kernel/mm/transparent_hugepage/enabled
echo madvise | sudo tee -a /sys/kernel/mm/transparent_hugepage/defrag
While NuoDB recommends that you specify madvise, specifying never also allows NuoDB to work correctly.

If you receive an error such as this:

cannot create /sys/kernel/mm/transparent_hugepage/enabled: Read-only file system

then refer to Disabling THP on Read-Only File Systems.

Disabling THP Permanently

To permanently disable THP, do one of the following:

  • Edit the kernel bootloader.

  • Edit your system startup script.

For either of these changes to take effect, you must restart your system. If it is not convenient to restart immediately after performing one of the above actions, see Disabling THP Until the Next Restart.

Editing the Kernel Bootloader

If you are using a bootloader, for example /etc/grub.conf, add the following to the end of the kernel boot line:

transparent_hugepage=madvise
Before editing your bootloader configuration, refer to your system documentation.

Editing Your System Startup Script

First, identify your system startup script. This is likely to be one of the following:

  • /etc/rc.local (Red Hat Enterprise Linux)

  • /etc/rc.d/rc.local

  • Something else specific to your platform

After identifying your system startup script, edit it to add the following lines:

test -f /sys/kernel/mm/transparent_hugepage/enabled \
    && echo madvise > /sys/kernel/mm/transparent_hugepage/enabled
test -f /sys/kernel/mm/transparent_hugepage/defrag \
    && echo madvise > /sys/kernel/mm/transparent_hugepage/defrag

To ensure that the system startup script is executed when the system reboots, make sure it has execute permissions by running chmod +x system-startup-script.

You must have root privileges to edit and change the permissions of this file.

Disabling THP on Read-Only File Systems

On some hosts, the /sys directory is mounted as a read-only file system; the disabling of THP requires additional steps on a read-only file system. To determine whether /sys is mounted as a read-only file system, run the following command:

grep sysfs /proc/mounts

You will see a line such as the following.

sysfs /sys sysfs ro,nosuid,nodev,noexec,relatime 0 0

If the first option is ro, as in this example, then the /sys directory is mounted as a read-only file system.

To disable THP on a read-only file system, do the following:

  1. Remount the /sys directory as read-write:

    sudo mount -o rw,remount /sys

  2. As a root user, change permissions as follows:

    chmod o+w /sys/kernel/mm/transparent_hugepage/enabled \
    /sys/kernel/mm/transparent_hugepage/defrag

Now you can run the commands from Disabling THP Until the Next Restart.

The steps documented in this section disable THP only until the next host restart. For information on permanently disabling THP, see Disabling THP Permanently.