HUGEADM(8)

💖 HUGEADM 💖

okay bestie, so this is hugeadm, and it lives in section 8 of the System Manager's Manual. it's a system-admin girlie, not a user-space one, so you already know it means business. 🫶

---

✨ NAME ✨

hugeadm — configure the system huge page pools 🐘✨

like. it sets up your huge pages. the big ones. the main character pages. 💅

---

✨ SYNOPSIS ✨

hugeadm [options]

that's it. that's the whole vibe. you run hugeadm and then you hand it some options and it does its thing. no positional args, no drama, just options. 🌸

ngl there's a LOT more coming — this is just the opening act and she has range. stay tuned bestie 💜

💖 DESCRIPTION 💖

okay so bestie, hugeadm is literally the main character of huge page management. it displays and configures the system's huge page pools, and the way it works is so iconic: each pool has a minimum and a maximum threshold, like a little range of vibes. 🌈

the minimum value gets allocated up front by the kernel and is guaranteed to stay as hugepages until you shrink the pool. periodt. so if you set a minimum, those pages are yours, no takebacks (unless you shrink).

if you set a maximum, the system will dynamically allocate pages whenever applications ask for more hugepages than the minimum size of the pool. but — and this is the important part, ngl — there is no guarantee that more pages than this minimum pool size can be allocated. so don't come for the kernel if it can't deliver. 💀

---

🎀 Options that create hugetlbfs mount points 🎀

these next ones literally create mounts for you. it's giving convenience.

• --create-mounts — creates mount points for each supported huge page size under /var/lib/hugetlbfs. after creation they are mounts and are owned by root:root with permissions set to 770. each mount point is named pagesize-<size in bytes>. 🫶
• --create-user-mounts=<user> — creates mount points for each supported huge page size under /var/lib/hugetlbfs/user/<user>. the naming is the same as --create-mounts. after creation they are mounted and are owned by <user>:root with permissions set to 700. 💜
• --create-group-mounts=<group> — creates mount points for each supported huge page size under /var/lib/hugetlbfs/group/<group>. naming? same as --create-mounts. after creation they are mounted and are owned by root:<group> with permissions set to 070. 🌸
• --create-global-mounts — creates mount points for each supported huge page size under /var/lib/hugetlbfs/global. yep, naming is the same as --create-mounts again. after creation they are mounted and are owned by root:root with permissions set to 1777. (that sticky bit is doing WORK, slay.) 👑

---

✨ Options that affect how mount points are created ✨

• --max-size — used in conjunction with --create-*-mounts. it limits the maximum amount of memory used by files within the mount point, rounded up to the nearest huge page size. this can be used, for example, to grant different huge page quotas to individual users or groups. it's giving quota queen. 💅
• --max-inodes — also used in conjunction with --create-*-mounts. it limits the number of inodes (e.g. files) that can be created on the new mount points. this limits the number of mappings that can be created on a mount point. it could be used, for example, to limit the number of application instances that used a mount point, as long as it was known how many inodes each application instance required. math girlies stay winning. 🧮

---

🦋 Options that display information about the pools 🦋

• --pool-list — this displays the Minimum, Current and Maximum number of huge pages in the pool for each pagesize supported by the system. let me break it down fr fr:
  • the "Minimum" value is the size of the static pool, and there will always be at least this number of hugepages in use by the system — either by applications or kept by the kernel in a reserved pool.
  • the "Current" value is the number of hugepages currently in use, either by applications or stored on the kernel's free list.
  • the "Maximum" value is the largest number of hugepages that can be in use at any given time.
• --set-recommended-min_free_kbytes — fragmentation avoidance in the kernel depends on avoiding pages of different mobility types being mixed with a pageblock arena — typically the size of the default huge page size. the more mixing that occurs, the less likely the huge page pool will be able to dynamically resize. the easiest means of avoiding mixing is to increase /proc/sys/vm/min_free_kbytes. this parameter sets min_free_kbytes to a recommended value to aid fragmentation avoidance. no cap, this one's actually important. 🔥
• --set-recommended-shmmax — the maximum shared memory segment size should be set to at least the size of the largest shared memory segment size you want available for applications using huge pages, via /proc/sys/kernel/shmmax. optionally, it can be set automatically to match the maximum possible size of all huge page allocations — and thus the maximum possible shared memory segment size — using this switch. ✨
• --set-shm-group=<gid|groupname> — users in the group specified in /proc/sys/vm/hugetlb_shm_group are granted full access to huge pages. the sysctl takes a numeric gid, but this hugeadm option can set it for you, using either a gid or a group name. so flexible, we love her. 💖
• --page-sizes — displays every page size supported by the system and has a pool configured. 💅
• --page-sizes-all — displays all page sizes supported by the system, even if no pool is available. completionist energy. ⭐
• --list-all-mounts — displays all active mount points for hugetlbfs. 🎀

---

🔧 Options that configure the pool 🔧

• --pool-pages-min=<size|DEFAULT>:[+|-]<pagecount|memsize<G|M|K>> — this option sets or adjusts the Minimum number of hugepages in the pool for pagesize size. size may be specified in bytes, or in kilobytes, megabytes, or gigabytes by appending K, M, or G respectively, or as DEFAULT, which uses the system's default huge page size for size. the pool size adjustment can be specified by pagecount pages, or by memsize if postfixed with G, M, or K for gigabytes, megabytes, or kilobytes respectively. if the adjustment is specified via memsize, then the pagecount will be calculated for you, based on page size size. the pool is set to pagecount pages if + or - are not specified; if + or - are specified, then the size of the pool will adjust by that amount.

⚠️ note that there is no guarantee that the system can allocate the hugepages requested for the Minimum pool. the size of the pools should be checked after executing this command to ensure they were successful. bestie, please check. i'm begging. 😭

• --obey-numa-mempol — this option requests that allocation of huge pages to the static pool with --pool-pages-min obey the NUMA memory policy of the current process. this policy can be explicitly specified using numactl or inherited from a parent process. inherited trauma but for memory policy 🫶
• --pool-pages-max=<size|DEFAULT>:[+|-]<pagecount|memsize<G|M|K>> — this option sets or adjusts the Maximum number of hugepages. note that while the Minimum number of pages are guaranteed to be available to applications, there is not a guarantee that the system can allocate the pages on demand when the number of huge pages requested by applications is between the Minimum and Maximum pool sizes. see --pool-pages-min for usage syntax. same syntax, different vibes. 💀
• --enable-zone-movable — this option enables the use of the MOVABLE zone for the allocation of hugepages. this zone is created when kernelcore= or movablecore= are specified on the kernel command line, but the zone is not used for the allocation of huge pages by default, as the intended use for the zone may be to guarantee that memory can be off-lined and hot-removed. the kernel guarantees that the pages within this zone can be reclaimed, unlike some kernel buffers for example. unless pages are locked with mlock(), the hugepage pool can grow to at least the size of the movable zone once this option is set. use sysctl to permanently enable the use of the MOVABLE zone for the allocation of huge pages. 🔥
• --disable-zone-movable — this option disables the use of the MOVABLE zone for the future allocation of huge pages. note that existing huge pages are not reclaimed from the zone. use sysctl to permanently disable the use of the MOVABLE zone for the allocation of huge pages. bye bye movable zone (eventually). 🙈
• --hard — this option is specified with --pool-pages-min to retry allocations multiple times on failure to allocate the desired count of pages. it initially tries to resize the pool up to 5 times, and continues to try if progress is being made towards the resize. she's persistent, we stan. 💪
• --add-temp-swap<=count> — this option is specified with --pool-pages-min to initialize a temporary swap file for the duration of the pool resize. when increasing the size of the pool, it can be necessary to reclaim pages so that contiguous memory is freed, and this often requires swap to be successful. swap is only created for a positive resize, and is then removed once the resize operation is completed. the default swap size is 5 huge pages; the optional argument <count> sets the swap size to <count> huge pages. ✨
• --add-ramdisk-swap — this option is specified with --pool-pages-min to initialize swap in memory on ram disks. when increasing the size of the pool, it can be necessary to reclaim pages so that contiguous memory is freed, and this often requires swap to be successful. if there isn't enough free disk space, swap can be initialized in RAM using this option. if the size of one ramdisk is not greater than the huge page size, then swap is initialized on multiple ramdisks. swap is only created for a positive resize, and by default is removed once the resize operation is completed. ramdisk girlies rise up 🧚
• --persist — this option is specified with --add-temp-swap or --add-ramdisk-swap to make the swap space persist after the resize operation is completed. the swap spaces can later be removed manually using the swapoff command. you've been warned, it stays. 🫶

---

🌈 Options that tune transparent huge page usage 🌈

• --thp-always — enable transparent huge pages always. ✨
• --thp-madvise — enable transparent huge pages only on madvised regions. 💅
• --thp-never — disable transparent huge pages. periodt. 🚫
• --thp-khugepaged-pages <pages to scan> — configure the number of pages that khugepaged should scan on each pass. 🔍
• --thp-khugepaged-scan-sleep <milliseconds> — configure how many milliseconds khugepaged should wait between passes. 💤
• --thp-khugepaged-alloc-sleep <milliseconds> — configure how many milliseconds khugepaged should wait after failing to allocate a huge page, to throttle the next attempt. 😮‍💨

---

💬 Options that affect the verbosity of libhugetlbfs 💬

• --verbose <level>, -v — the default value for the verbosity level is 1, and the range of the value can be set with --verbose from 0 to 99. the higher the value, the more verbose the library will be. 0 is quiet, and 3 will output much debugging information. the verbosity level is increased by one each time -v is specified. so -vvv is just... a lot of talking. iconic. 🗣️

---

💖 SEE ALSO 💖

okay so if you're nosy (love that for you) and you wanna go read the other pages in this little family, here's the whole squad:

• oprofile(1)
• pagesize(1)
• libhugetlbfs(7)
• hugectl(8)

go forth and read, bestie, they're all part of the same friend group 🫶

---

🌸 AUTHORS 🌸

so like… who even made this? libhugetlbfs was written by various people on the libhugetlbfs-devel mailing list. it's giving collaborative slay, it's giving community effort, no single main character here — just a whole group chat of legends ✨👑

---

and that's the whole page, babe, you made it to the end 🎀 this one's from October 1, 2009, and it's page HUGEADM(8) — go hug a huge page for me 💅🦋