Provided by: libhugetlbfs-bin_2.23-5_amd64 
NAME
hugeadm - Configure the system huge page pools
SYNOPSIS
hugeadm [options]
DESCRIPTION
hugeadm displays and configures the systems huge page pools. The size of the pools is set
as a minimum and maximum threshold. The minimum value is allocated up front by the kernel
and guaranteed to remain as hugepages until the pool is shrunk. If a maximum is set, the
system will dynamically allocate pages if applications request more hugepages than the
minimum size of the pool. There is no guarantee that more pages than this minimum pool
size can be allocated.
The following options create mounts hugetlbfs mount points.
--create-mounts
This 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>
This creates mount points for each supported huge page size under
/var/lib/hugetlbfs/user/<user>. Mount point 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>
This creates mount points for each supported huge page size under
/var/lib/hugetlbfs/group/<group>. Mount point naming is the same as --create-
mounts. After creation they are mounted and are owned by root:<group> with
permissions set to 070.
--create-global-mounts
This creates mount points for each supported huge page size under
/var/lib/hugetlbfs/global. Mount point naming is the same as --create-mounts.
After creation they are mounted and are owned by root:root with permissions set to
1777.
The following options affect how mount points are created.
--max-size
This option is 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.
--max-inodes
This option is 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.
The following options 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. 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 kernels 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.
--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 group name.
--page-sizes
This displays every page size supported by the system and has a pool configured.
--page-sizes-all
This displays all page sizes supported by the system, even if no pool is available.
--list-all-mounts
This displays all active mount points for hugetlbfs.
The following options 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.
--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.
--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 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.
--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.
--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.
--add-temp-swap<=count>
This options 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.
--persist
This option is specified with the --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.
The following options tune the 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
--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.
The following options 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.
SEE ALSO
oprofile(1), pagesize(1), libhugetlbfs(7), hugectl(8),
AUTHORS
libhugetlbfs was written by various people on the libhugetlbfs-devel mailing list.
October 1, 2009 HUGEADM(8)