HUGEADM(8)HUGEADM(8)NAMEhugeadm - Configure the system huge page pools
SYNOPSIShugeadm [options]
DESCRIPTIONhugeadm 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 indi‐
vidual 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 sys‐
tem, 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 mix‐
ing 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/ker‐
nel/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 speci‐
fied 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 sys‐
tem can allocate the pages on demand when the number of huge
pages requested by applications is between the Minimum and Maxi‐
mum pool sizes. See --pool-pages-min for usage syntax.
--enable-zone-movable
This option enables the use of the MOVABLE zone for the alloca‐
tion of hugepages. This zone is created when kernelcore= or mov‐
ablecore= 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 alloca‐
tions 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 com‐
pleted. 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 com‐
pleted.
--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-khugepages-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 ALSOoprofile(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)
