aboutsummaryrefslogtreecommitdiffstats
path: root/docs/gettingstarted/users/configuring/hugepages.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/gettingstarted/users/configuring/hugepages.rst')
-rw-r--r--docs/gettingstarted/users/configuring/hugepages.rst61
1 files changed, 61 insertions, 0 deletions
diff --git a/docs/gettingstarted/users/configuring/hugepages.rst b/docs/gettingstarted/users/configuring/hugepages.rst
new file mode 100644
index 00000000000..42f6aa30282
--- /dev/null
+++ b/docs/gettingstarted/users/configuring/hugepages.rst
@@ -0,0 +1,61 @@
+.. _hugepages:
+
+Huge Pages
+----------
+
+VPP requires *'hugepages'* to run. VPP will overwrite existing hugepage
+settings when VPP is installed. By default, VPP sets the number of hugepages on
+a system to 1024 2M hugepages (1G hugepages are no longer supported). This is
+the number of hugepages on the system, not just used by VPP. When VPP is
+installed, the following file is copied to the system and used to apply the
+hugepage settings on VPP installation and system reboot:
+
+.. code-block:: console
+
+ $ cat /etc/sysctl.d/80-vpp.conf
+ # Number of 2MB hugepages desired
+ vm.nr_hugepages=1024
+
+ # Must be greater than or equal to (2 * vm.nr_hugepages).
+ vm.max_map_count=3096
+
+ # All groups allowed to access hugepages
+ vm.hugetlb_shm_group=0
+
+ # Shared Memory Max must be greator or equal to the total size of hugepages.
+ # For 2MB pages, TotalHugepageSize = vm.nr_hugepages * 2 * 1024 * 1024
+ # If the existing kernel.shmmax setting (cat /sys/proc/kernel/shmmax)
+ # is greater than the calculated TotalHugepageSize then set this parameter
+ # to current shmmax value.
+ kernel.shmmax=2147483648
+
+Depending on how the system is being used, this file can be updated to adjust
+the number of hugepages reserved on a system. Below are some examples of
+possible values.
+
+For a small VM with minimal workload:
+
+.. code-block:: console
+
+ vm.nr_hugepages=512
+ vm.max_map_count=2048
+ kernel.shmmax=1073741824
+
+For a large system running multiple VMs, each needing its own set of hugepages:
+
+.. code-block:: console
+
+ vm.nr_hugepages=32768
+ vm.max_map_count=66560
+ kernel.shmmax=68719476736
+
+
+.. note::
+
+ If VPP is being run in a Virtual Machine (VM), the VM must have hugepage
+ backing. When VPP is installed, it will attempt to overwrite existing
+ hugepage setting. If the VM does not have hugepage backing, this will fail,
+ but this may go unnoticed. When the VM is rebooted, on system startup,
+ *'vm.nr_hugepages'* will be reapplied, will fail, and the VM will abort kernel
+ boot, locking up the VM. To avoid this scenario, ensure the VM has enough
+ hugepage backing.