vm.rst

   1===============================
   2Documentation for /proc/sys/vm/
   3===============================
   4
   5kernel version 2.6.29
   6
   7Copyright (c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>
   8
   9Copyright (c) 2008         Peter W. Morreale <pmorreale@novell.com>
  10
  11For general info and legal blurb, please look in index.rst.
  12
  13------------------------------------------------------------------------------
  14
  15This file contains the documentation for the sysctl files in
  16/proc/sys/vm and is valid for Linux kernel version 2.6.29.
  17
  18The files in this directory can be used to tune the operation
  19of the virtual memory (VM) subsystem of the Linux kernel and
  20the writeout of dirty data to disk.
  21
  22Default values and initialization routines for most of these
  23files can be found in mm/swap.c.
  24
  25Currently, these files are in /proc/sys/vm:
  26
  27- admin_reserve_kbytes
  28- compact_memory
  29- compaction_proactiveness
  30- compact_unevictable_allowed
  31- defrag_mode
  32- dirty_background_bytes
  33- dirty_background_ratio
  34- dirty_bytes
  35- dirty_expire_centisecs
  36- dirty_ratio
  37- dirtytime_expire_seconds
  38- dirty_writeback_centisecs
  39- drop_caches
  40- enable_soft_offline
  41- extfrag_threshold
  42- highmem_is_dirtyable
  43- hugetlb_shm_group
  44- laptop_mode
  45- legacy_va_layout
  46- lowmem_reserve_ratio
  47- max_map_count
  48- mem_profiling         (only if CONFIG_MEM_ALLOC_PROFILING=y)
  49- memory_failure_early_kill
  50- memory_failure_recovery
  51- min_free_kbytes
  52- min_slab_ratio
  53- min_unmapped_ratio
  54- mmap_min_addr
  55- mmap_rnd_bits
  56- mmap_rnd_compat_bits
  57- nr_hugepages
  58- nr_hugepages_mempolicy
  59- nr_overcommit_hugepages
  60- nr_trim_pages         (only if CONFIG_MMU=n)
  61- numa_zonelist_order
  62- oom_dump_tasks
  63- oom_kill_allocating_task
  64- overcommit_kbytes
  65- overcommit_memory
  66- overcommit_ratio
  67- page-cluster
  68- page_lock_unfairness
  69- panic_on_oom
  70- percpu_pagelist_high_fraction
  71- stat_interval
  72- stat_refresh
  73- numa_stat
  74- swappiness
  75- unprivileged_userfaultfd
  76- user_reserve_kbytes
  77- vfs_cache_pressure
  78- vfs_cache_pressure_denom
  79- watermark_boost_factor
  80- watermark_scale_factor
  81- zone_reclaim_mode
  82
  83
  84admin_reserve_kbytes
  85====================
  86
  87The amount of free memory in the system that should be reserved for users
  88with the capability cap_sys_admin.
  89
  90admin_reserve_kbytes defaults to min(3% of free pages, 8MB)
  91
  92That should provide enough for the admin to log in and kill a process,
  93if necessary, under the default overcommit 'guess' mode.
  94
  95Systems running under overcommit 'never' should increase this to account
  96for the full Virtual Memory Size of programs used to recover. Otherwise,
  97root may not be able to log in to recover the system.
  98
  99How do you calculate a minimum useful reserve?
 100
 101sshd or login + bash (or some other shell) + top (or ps, kill, etc.)
 102
 103For overcommit 'guess', we can sum resident set sizes (RSS).
 104On x86_64 this is about 8MB.
 105
 106For overcommit 'never', we can take the max of their virtual sizes (VSZ)
 107and add the sum of their RSS.
 108On x86_64 this is about 128MB.
 109
 110Changing this takes effect whenever an application requests memory.
 111
 112
 113compact_memory
 114==============
 115
 116Available only when CONFIG_COMPACTION is set. When 1 is written to the file,
 117all zones are compacted such that free memory is available in contiguous
 118blocks where possible. This can be important for example in the allocation of
 119huge pages although processes will also directly compact memory as required.
 120
 121compaction_proactiveness
 122========================
 123
 124This tunable takes a value in the range [0, 100] with a default value of
 12520. This tunable determines how aggressively compaction is done in the
 126background. Write of a non zero value to this tunable will immediately
 127trigger the proactive compaction. Setting it to 0 disables proactive compaction.
 128
 129Note that compaction has a non-trivial system-wide impact as pages
 130belonging to different processes are moved around, which could also lead
 131to latency spikes in unsuspecting applications. The kernel employs
 132various heuristics to avoid wasting CPU cycles if it detects that
 133proactive compaction is not being effective.
 134
 135Setting the value above 80 will, in addition to lowering the acceptable level
 136of fragmentation, make the compaction code more sensitive to increases in
 137fragmentation, i.e. compaction will trigger more often, but reduce
 138fragmentation by a smaller amount.
 139This makes the fragmentation level more stable over time.
 140
 141Be careful when setting it to extreme values like 100, as that may
 142cause excessive background compaction activity.
 143
 144compact_unevictable_allowed
 145===========================
 146
 147Available only when CONFIG_COMPACTION is set. When set to 1, compaction is
 148allowed to examine the unevictable lru (mlocked pages) for pages to compact.
 149This should be used on systems where stalls for minor page faults are an
 150acceptable trade for large contiguous free memory.  Set to 0 to prevent
 151compaction from moving pages that are unevictable.  Default value is 1.
 152On CONFIG_PREEMPT_RT the default value is 0 in order to avoid a page fault, due
 153to compaction, which would block the task from becoming active until the fault
 154is resolved.
 155
 156defrag_mode
 157===========
 158
 159When set to 1, the page allocator tries harder to avoid fragmentation
 160and maintain the ability to produce huge pages / higher-order pages.
 161
 162It is recommended to enable this right after boot, as fragmentation,
 163once it occurred, can be long-lasting or even permanent.
 164
 165dirty_background_bytes
 166======================
 167
 168Contains the amount of dirty memory at which the background kernel
 169flusher threads will start writeback.
 170
 171Note:
 172  dirty_background_bytes is the counterpart of dirty_background_ratio. Only
 173  one of them may be specified at a time. When one sysctl is written it is
 174  immediately taken into account to evaluate the dirty memory limits and the
 175  other appears as 0 when read.
 176
 177
 178dirty_background_ratio
 179======================
 180
 181Contains, as a percentage of total available memory that contains free pages
 182and reclaimable pages, the number of pages at which the background kernel
 183flusher threads will start writing out dirty data.
 184
 185The total available memory is not equal to total system memory.
 186
 187
 188dirty_bytes
 189===========
 190
 191Contains the amount of dirty memory at which a process generating disk writes
 192will itself start writeback.
 193
 194Note: dirty_bytes is the counterpart of dirty_ratio. Only one of them may be
 195specified at a time. When one sysctl is written it is immediately taken into
 196account to evaluate the dirty memory limits and the other appears as 0 when
 197read.
 198
 199Note: the minimum value allowed for dirty_bytes is two pages (in bytes); any
 200value lower than this limit will be ignored and the old configuration will be
 201retained.
 202
 203
 204dirty_expire_centisecs
 205======================
 206
 207This tunable is used to define when dirty data is old enough to be eligible
 208for writeout by the kernel flusher threads.  It is expressed in 100'ths
 209of a second.  Data which has been dirty in-memory for longer than this
 210interval will be written out next time a flusher thread wakes up.
 211
 212
 213dirty_ratio
 214===========
 215
 216Contains, as a percentage of total available memory that contains free pages
 217and reclaimable pages, the number of pages at which a process which is
 218generating disk writes will itself start writing out dirty data.
 219
 220The total available memory is not equal to total system memory.
 221
 222
 223dirtytime_expire_seconds
 224========================
 225
 226When a lazytime inode is constantly having its pages dirtied, the inode with
 227an updated timestamp will never get chance to be written out.  And, if the
 228only thing that has happened on the file system is a dirtytime inode caused
 229by an atime update, a worker will be scheduled to make sure that inode
 230eventually gets pushed out to disk.  This tunable is used to define when dirty
 231inode is old enough to be eligible for writeback by the kernel flusher threads.
 232And, it is also used as the interval to wakeup dirtytime_writeback thread.
 233
 234Setting this to zero disables periodic dirtytime writeback.
 235
 236
 237dirty_writeback_centisecs
 238=========================
 239
 240The kernel flusher threads will periodically wake up and write `old` data
 241out to disk.  This tunable expresses the interval between those wakeups, in
 242100'ths of a second.
 243
 244Setting this to zero disables periodic writeback altogether.
 245
 246
 247drop_caches
 248===========
 249
 250Writing to this will cause the kernel to drop clean caches, as well as
 251reclaimable slab objects like dentries and inodes.  Once dropped, their
 252memory becomes free.
 253
 254To free pagecache::
 255
 256	echo 1 > /proc/sys/vm/drop_caches
 257
 258To free reclaimable slab objects (includes dentries and inodes)::
 259
 260	echo 2 > /proc/sys/vm/drop_caches
 261
 262To free slab objects and pagecache::
 263
 264	echo 3 > /proc/sys/vm/drop_caches
 265
 266This is a non-destructive operation and will not free any dirty objects.
 267To increase the number of objects freed by this operation, the user may run
 268`sync` prior to writing to /proc/sys/vm/drop_caches.  This will minimize the
 269number of dirty objects on the system and create more candidates to be
 270dropped.
 271
 272This file is not a means to control the growth of the various kernel caches
 273(inodes, dentries, pagecache, etc...)  These objects are automatically
 274reclaimed by the kernel when memory is needed elsewhere on the system.
 275
 276Use of this file can cause performance problems.  Since it discards cached
 277objects, it may cost a significant amount of I/O and CPU to recreate the
 278dropped objects, especially if they were under heavy use.  Because of this,
 279use outside of a testing or debugging environment is not recommended.
 280
 281You may see informational messages in your kernel log when this file is
 282used::
 283
 284	cat (1234): drop_caches: 3
 285
 286These are informational only.  They do not mean that anything is wrong
 287with your system.  To disable them, echo 4 (bit 2) into drop_caches.
 288
 289enable_soft_offline
 290===================
 291Correctable memory errors are very common on servers. Soft-offline is kernel's
 292solution for memory pages having (excessive) corrected memory errors.
 293
 294For different types of page, soft-offline has different behaviors / costs.
 295
 296- For a raw error page, soft-offline migrates the in-use page's content to
 297  a new raw page.
 298
 299- For a page that is part of a transparent hugepage, soft-offline splits the
 300  transparent hugepage into raw pages, then migrates only the raw error page.
 301  As a result, user is transparently backed by 1 less hugepage, impacting
 302  memory access performance.
 303
 304- For a page that is part of a HugeTLB hugepage, soft-offline first migrates
 305  the entire HugeTLB hugepage, during which a free hugepage will be consumed
 306  as migration target.  Then the original hugepage is dissolved into raw
 307  pages without compensation, reducing the capacity of the HugeTLB pool by 1.
 308
 309It is user's call to choose between reliability (staying away from fragile
 310physical memory) vs performance / capacity implications in transparent and
 311HugeTLB cases.
 312
 313For all architectures, enable_soft_offline controls whether to soft offline
 314memory pages.  When set to 1, kernel attempts to soft offline the pages
 315whenever it thinks needed.  When set to 0, kernel returns EOPNOTSUPP to
 316the request to soft offline the pages.  Its default value is 1.
 317
 318It is worth mentioning that after setting enable_soft_offline to 0, the
 319following requests to soft offline pages will not be performed:
 320
 321- Request to soft offline pages from RAS Correctable Errors Collector.
 322
 323- On ARM, the request to soft offline pages from GHES driver.
 324
 325- On PARISC, the request to soft offline pages from Page Deallocation Table.
 326
 327extfrag_threshold
 328=================
 329
 330This parameter affects whether the kernel will compact memory or direct
 331reclaim to satisfy a high-order allocation. The extfrag/extfrag_index file in
 332debugfs shows what the fragmentation index for each order is in each zone in
 333the system. Values tending towards 0 imply allocations would fail due to lack
 334of memory, values towards 1000 imply failures are due to fragmentation and -1
 335implies that the allocation will succeed as long as watermarks are met.
 336
 337The kernel will not compact memory in a zone if the
 338fragmentation index is <= extfrag_threshold. The default value is 500.
 339
 340
 341highmem_is_dirtyable
 342====================
 343
 344Available only for systems with CONFIG_HIGHMEM enabled (32b systems).
 345
 346This parameter controls whether the high memory is considered for dirty
 347writers throttling.  This is not the case by default which means that
 348only the amount of memory directly visible/usable by the kernel can
 349be dirtied. As a result, on systems with a large amount of memory and
 350lowmem basically depleted writers might be throttled too early and
 351streaming writes can get very slow.
 352
 353Changing the value to non zero would allow more memory to be dirtied
 354and thus allow writers to write more data which can be flushed to the
 355storage more effectively. Note this also comes with a risk of pre-mature
 356OOM killer because some writers (e.g. direct block device writes) can
 357only use the low memory and they can fill it up with dirty data without
 358any throttling.
 359
 360
 361hugetlb_shm_group
 362=================
 363
 364hugetlb_shm_group contains group id that is allowed to create SysV
 365shared memory segment using hugetlb page.
 366
 367
 368laptop_mode
 369===========
 370
 371laptop_mode is a knob that controls "laptop mode". All the things that are
 372controlled by this knob are discussed in Documentation/admin-guide/laptops/laptop-mode.rst.
 373
 374
 375legacy_va_layout
 376================
 377
 378If non-zero, this sysctl disables the new 32-bit mmap layout - the kernel
 379will use the legacy (2.4) layout for all processes.
 380
 381
 382lowmem_reserve_ratio
 383====================
 384
 385For some specialised workloads on highmem machines it is dangerous for
 386the kernel to allow process memory to be allocated from the "lowmem"
 387zone.  This is because that memory could then be pinned via the mlock()
 388system call, or by unavailability of swapspace.
 389
 390And on large highmem machines this lack of reclaimable lowmem memory
 391can be fatal.
 392
 393So the Linux page allocator has a mechanism which prevents allocations
 394which *could* use highmem from using too much lowmem.  This means that
 395a certain amount of lowmem is defended from the possibility of being
 396captured into pinned user memory.
 397
 398(The same argument applies to the old 16 megabyte ISA DMA region.  This
 399mechanism will also defend that region from allocations which could use
 400highmem or lowmem).
 401
 402The `lowmem_reserve_ratio` tunable determines how aggressive the kernel is
 403in defending these lower zones.
 404
 405If you have a machine which uses highmem or ISA DMA and your
 406applications are using mlock(), or if you are running with no swap then
 407you probably should change the lowmem_reserve_ratio setting.
 408
 409The lowmem_reserve_ratio is an array. You can see them by reading this file::
 410
 411	% cat /proc/sys/vm/lowmem_reserve_ratio
 412	256     256     32
 413
 414But, these values are not used directly. The kernel calculates # of protection
 415pages for each zones from them. These are shown as array of protection pages
 416in /proc/zoneinfo like the following. (This is an example of x86-64 box).
 417Each zone has an array of protection pages like this::
 418
 419  Node 0, zone      DMA
 420    pages free     1355
 421          min      3
 422          low      3
 423          high     4
 424	:
 425	:
 426      numa_other   0
 427          protection: (0, 2004, 2004, 2004)
 428	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 429    pagesets
 430      cpu: 0 pcp: 0
 431          :
 432
 433These protections are added to score to judge whether this zone should be used
 434for page allocation or should be reclaimed.
 435
 436In this example, if normal pages (index=2) are required to this DMA zone and
 437watermark[WMARK_HIGH] is used for watermark, the kernel judges this zone should
 438not be used because pages_free(1355) is smaller than watermark + protection[2]
 439(4 + 2004 = 2008). If this protection value is 0, this zone would be used for
 440normal page requirement. If requirement is DMA zone(index=0), protection[0]
 441(=0) is used.
 442
 443zone[i]'s protection[j] is calculated by following expression::
 444
 445  (i < j):
 446    zone[i]->protection[j]
 447    = (total sums of managed_pages from zone[i+1] to zone[j] on the node)
 448      / lowmem_reserve_ratio[i];
 449  (i = j):
 450     (should not be protected. = 0;
 451  (i > j):
 452     (not necessary, but looks 0)
 453
 454The default values of lowmem_reserve_ratio[i] are
 455
 456    === ====================================
 457    256 (if zone[i] means DMA or DMA32 zone)
 458    32  (others)
 459    === ====================================
 460
 461As above expression, they are reciprocal number of ratio.
 462256 means 1/256. # of protection pages becomes about "0.39%" of total managed
 463pages of higher zones on the node.
 464
 465If you would like to protect more pages, smaller values are effective.
 466The minimum value is 1 (1/1 -> 100%). The value less than 1 completely
 467disables protection of the pages.
 468
 469
 470max_map_count
 471=============
 472
 473This file contains the maximum number of memory map areas a process
 474may have. Memory map areas are used as a side-effect of calling
 475malloc, directly by mmap, mprotect, and madvise, and also when loading
 476shared libraries.
 477
 478While most applications need less than a thousand maps, certain
 479programs, particularly malloc debuggers, may consume lots of them,
 480e.g., up to one or two maps per allocation.
 481
 482The default value is 65530.
 483
 484
 485mem_profiling
 486==============
 487
 488Enable memory profiling (when CONFIG_MEM_ALLOC_PROFILING=y)
 489
 4901: Enable memory profiling.
 491
 4920: Disable memory profiling.
 493
 494Enabling memory profiling introduces a small performance overhead for all
 495memory allocations.
 496
 497The default value depends on CONFIG_MEM_ALLOC_PROFILING_ENABLED_BY_DEFAULT.
 498
 499When CONFIG_MEM_ALLOC_PROFILING_DEBUG=y, this control is read-only to avoid
 500warnings produced by allocations made while profiling is disabled and freed
 501when it's enabled.
 502
 503
 504memory_failure_early_kill
 505=========================
 506
 507Control how to kill processes when uncorrected memory error (typically
 508a 2bit error in a memory module) is detected in the background by hardware
 509that cannot be handled by the kernel. In some cases (like the page
 510still having a valid copy on disk) the kernel will handle the failure
 511transparently without affecting any applications. But if there is
 512no other up-to-date copy of the data it will kill to prevent any data
 513corruptions from propagating.
 514
 5151: Kill all processes that have the corrupted and not reloadable page mapped
 516as soon as the corruption is detected.  Note this is not supported
 517for a few types of pages, like kernel internally allocated data or
 518the swap cache, but works for the majority of user pages.
 519
 5200: Only unmap the corrupted page from all processes and only kill a process
 521who tries to access it.
 522
 523The kill is done using a catchable SIGBUS with BUS_MCEERR_AO, so processes can
 524handle this if they want to.
 525
 526This is only active on architectures/platforms with advanced machine
 527check handling and depends on the hardware capabilities.
 528
 529Applications can override this setting individually with the PR_MCE_KILL prctl
 530
 531
 532memory_failure_recovery
 533=======================
 534
 535Enable memory failure recovery (when supported by the platform)
 536
 5371: Attempt recovery.
 538
 5390: Always panic on a memory failure.
 540
 541
 542min_free_kbytes
 543===============
 544
 545This is used to force the Linux VM to keep a minimum number
 546of kilobytes free.  The VM uses this number to compute a
 547watermark[WMARK_MIN] value for each lowmem zone in the system.
 548Each lowmem zone gets a number of reserved free pages based
 549proportionally on its size.
 550
 551Some minimal amount of memory is needed to satisfy PF_MEMALLOC
 552allocations; if you set this to lower than 1024KB, your system will
 553become subtly broken, and prone to deadlock under high loads.
 554
 555Setting this too high will OOM your machine instantly.
 556
 557
 558min_slab_ratio
 559==============
 560
 561This is available only on NUMA kernels.
 562
 563A percentage of the total pages in each zone.  On Zone reclaim
 564(fallback from the local zone occurs) slabs will be reclaimed if more
 565than this percentage of pages in a zone are reclaimable slab pages.
 566This insures that the slab growth stays under control even in NUMA
 567systems that rarely perform global reclaim.
 568
 569The default is 5 percent.
 570
 571Note that slab reclaim is triggered in a per zone / node fashion.
 572The process of reclaiming slab memory is currently not node specific
 573and may not be fast.
 574
 575
 576min_unmapped_ratio
 577==================
 578
 579This is available only on NUMA kernels.
 580
 581This is a percentage of the total pages in each zone. Zone reclaim will
 582only occur if more than this percentage of pages are in a state that
 583zone_reclaim_mode allows to be reclaimed.
 584
 585If zone_reclaim_mode has the value 4 OR'd, then the percentage is compared
 586against all file-backed unmapped pages including swapcache pages and tmpfs
 587files. Otherwise, only unmapped pages backed by normal files but not tmpfs
 588files and similar are considered.
 589
 590The default is 1 percent.
 591
 592
 593mmap_min_addr
 594=============
 595
 596This file indicates the amount of address space  which a user process will
 597be restricted from mmapping.  Since kernel null dereference bugs could
 598accidentally operate based on the information in the first couple of pages
 599of memory userspace processes should not be allowed to write to them.  By
 600default this value is set to 0 and no protections will be enforced by the
 601security module.  Setting this value to something like 64k will allow the
 602vast majority of applications to work correctly and provide defense in depth
 603against future potential kernel bugs.
 604
 605
 606mmap_rnd_bits
 607=============
 608
 609This value can be used to select the number of bits to use to
 610determine the random offset to the base address of vma regions
 611resulting from mmap allocations on architectures which support
 612tuning address space randomization.  This value will be bounded
 613by the architecture's minimum and maximum supported values.
 614
 615This value can be changed after boot using the
 616/proc/sys/vm/mmap_rnd_bits tunable
 617
 618
 619mmap_rnd_compat_bits
 620====================
 621
 622This value can be used to select the number of bits to use to
 623determine the random offset to the base address of vma regions
 624resulting from mmap allocations for applications run in
 625compatibility mode on architectures which support tuning address
 626space randomization.  This value will be bounded by the
 627architecture's minimum and maximum supported values.
 628
 629This value can be changed after boot using the
 630/proc/sys/vm/mmap_rnd_compat_bits tunable
 631
 632
 633nr_hugepages
 634============
 635
 636Change the minimum size of the hugepage pool.
 637
 638See Documentation/admin-guide/mm/hugetlbpage.rst
 639
 640
 641hugetlb_optimize_vmemmap
 642========================
 643
 644This knob is not available when the size of 'struct page' (a structure defined
 645in include/linux/mm_types.h) is not power of two (an unusual system config could
 646result in this).
 647
 648Enable (set to 1) or disable (set to 0) HugeTLB Vmemmap Optimization (HVO).
 649
 650Once enabled, the vmemmap pages of subsequent allocation of HugeTLB pages from
 651buddy allocator will be optimized (7 pages per 2MB HugeTLB page and 4095 pages
 652per 1GB HugeTLB page), whereas already allocated HugeTLB pages will not be
 653optimized.  When those optimized HugeTLB pages are freed from the HugeTLB pool
 654to the buddy allocator, the vmemmap pages representing that range needs to be
 655remapped again and the vmemmap pages discarded earlier need to be rellocated
 656again.  If your use case is that HugeTLB pages are allocated 'on the fly' (e.g.
 657never explicitly allocating HugeTLB pages with 'nr_hugepages' but only set
 658'nr_overcommit_hugepages', those overcommitted HugeTLB pages are allocated 'on
 659the fly') instead of being pulled from the HugeTLB pool, you should weigh the
 660benefits of memory savings against the more overhead (~2x slower than before)
 661of allocation or freeing HugeTLB pages between the HugeTLB pool and the buddy
 662allocator.  Another behavior to note is that if the system is under heavy memory
 663pressure, it could prevent the user from freeing HugeTLB pages from the HugeTLB
 664pool to the buddy allocator since the allocation of vmemmap pages could be
 665failed, you have to retry later if your system encounter this situation.
 666
 667Once disabled, the vmemmap pages of subsequent allocation of HugeTLB pages from
 668buddy allocator will not be optimized meaning the extra overhead at allocation
 669time from buddy allocator disappears, whereas already optimized HugeTLB pages
 670will not be affected.  If you want to make sure there are no optimized HugeTLB
 671pages, you can set "nr_hugepages" to 0 first and then disable this.  Note that
 672writing 0 to nr_hugepages will make any "in use" HugeTLB pages become surplus
 673pages.  So, those surplus pages are still optimized until they are no longer
 674in use.  You would need to wait for those surplus pages to be released before
 675there are no optimized pages in the system.
 676
 677
 678nr_hugepages_mempolicy
 679======================
 680
 681Change the size of the hugepage pool at run-time on a specific
 682set of NUMA nodes.
 683
 684See Documentation/admin-guide/mm/hugetlbpage.rst
 685
 686
 687nr_overcommit_hugepages
 688=======================
 689
 690Change the maximum size of the hugepage pool. The maximum is
 691nr_hugepages + nr_overcommit_hugepages.
 692
 693See Documentation/admin-guide/mm/hugetlbpage.rst
 694
 695
 696nr_trim_pages
 697=============
 698
 699This is available only on NOMMU kernels.
 700
 701This value adjusts the excess page trimming behaviour of power-of-2 aligned
 702NOMMU mmap allocations.
 703
 704A value of 0 disables trimming of allocations entirely, while a value of 1
 705trims excess pages aggressively. Any value >= 1 acts as the watermark where
 706trimming of allocations is initiated.
 707
 708The default value is 1.
 709
 710See Documentation/admin-guide/mm/nommu-mmap.rst for more information.
 711
 712
 713numa_zonelist_order
 714===================
 715
 716This sysctl is only for NUMA and it is deprecated. Anything but
 717Node order will fail!
 718
 719'where the memory is allocated from' is controlled by zonelists.
 720
 721(This documentation ignores ZONE_HIGHMEM/ZONE_DMA32 for simple explanation.
 722you may be able to read ZONE_DMA as ZONE_DMA32...)
 723
 724In non-NUMA case, a zonelist for GFP_KERNEL is ordered as following.
 725ZONE_NORMAL -> ZONE_DMA
 726This means that a memory allocation request for GFP_KERNEL will
 727get memory from ZONE_DMA only when ZONE_NORMAL is not available.
 728
 729In NUMA case, you can think of following 2 types of order.
 730Assume 2 node NUMA and below is zonelist of Node(0)'s GFP_KERNEL::
 731
 732  (A) Node(0) ZONE_NORMAL -> Node(0) ZONE_DMA -> Node(1) ZONE_NORMAL
 733  (B) Node(0) ZONE_NORMAL -> Node(1) ZONE_NORMAL -> Node(0) ZONE_DMA.
 734
 735Type(A) offers the best locality for processes on Node(0), but ZONE_DMA
 736will be used before ZONE_NORMAL exhaustion. This increases possibility of
 737out-of-memory(OOM) of ZONE_DMA because ZONE_DMA is tend to be small.
 738
 739Type(B) cannot offer the best locality but is more robust against OOM of
 740the DMA zone.
 741
 742Type(A) is called as "Node" order. Type (B) is "Zone" order.
 743
 744"Node order" orders the zonelists by node, then by zone within each node.
 745Specify "[Nn]ode" for node order
 746
 747"Zone Order" orders the zonelists by zone type, then by node within each
 748zone.  Specify "[Zz]one" for zone order.
 749
 750Specify "[Dd]efault" to request automatic configuration.
 751
 752On 32-bit, the Normal zone needs to be preserved for allocations accessible
 753by the kernel, so "zone" order will be selected.
 754
 755On 64-bit, devices that require DMA32/DMA are relatively rare, so "node"
 756order will be selected.
 757
 758Default order is recommended unless this is causing problems for your
 759system/application.
 760
 761
 762oom_dump_tasks
 763==============
 764
 765Enables a system-wide task dump (excluding kernel threads) to be produced
 766when the kernel performs an OOM-killing and includes such information as
 767pid, uid, tgid, vm size, rss, pgtables_bytes, swapents, oom_score_adj
 768score, and name.  This is helpful to determine why the OOM killer was
 769invoked, to identify the rogue task that caused it, and to determine why
 770the OOM killer chose the task it did to kill.
 771
 772If this is set to zero, this information is suppressed.  On very
 773large systems with thousands of tasks it may not be feasible to dump
 774the memory state information for each one.  Such systems should not
 775be forced to incur a performance penalty in OOM conditions when the
 776information may not be desired.
 777
 778If this is set to non-zero, this information is shown whenever the
 779OOM killer actually kills a memory-hogging task.
 780
 781The default value is 1 (enabled).
 782
 783
 784oom_kill_allocating_task
 785========================
 786
 787This enables or disables killing the OOM-triggering task in
 788out-of-memory situations.
 789
 790If this is set to zero, the OOM killer will scan through the entire
 791tasklist and select a task based on heuristics to kill.  This normally
 792selects a rogue memory-hogging task that frees up a large amount of
 793memory when killed.
 794
 795If this is set to non-zero, the OOM killer simply kills the task that
 796triggered the out-of-memory condition.  This avoids the expensive
 797tasklist scan.
 798
 799If panic_on_oom is selected, it takes precedence over whatever value
 800is used in oom_kill_allocating_task.
 801
 802The default value is 0.
 803
 804
 805overcommit_kbytes
 806=================
 807
 808When overcommit_memory is set to 2, the committed address space is not
 809permitted to exceed swap plus this amount of physical RAM. See below.
 810
 811Note: overcommit_kbytes is the counterpart of overcommit_ratio. Only one
 812of them may be specified at a time. Setting one disables the other (which
 813then appears as 0 when read).
 814
 815
 816overcommit_memory
 817=================
 818
 819This value contains a flag that enables memory overcommitment.
 820
 821When this flag is 0, the kernel compares the userspace memory request
 822size against total memory plus swap and rejects obvious overcommits.
 823
 824When this flag is 1, the kernel pretends there is always enough
 825memory until it actually runs out.
 826
 827When this flag is 2, the kernel uses a "never overcommit"
 828policy that attempts to prevent any overcommit of memory.
 829Note that user_reserve_kbytes affects this policy.
 830
 831This feature can be very useful because there are a lot of
 832programs that malloc() huge amounts of memory "just-in-case"
 833and don't use much of it.
 834
 835The default value is 0.
 836
 837See Documentation/mm/overcommit-accounting.rst and
 838mm/util.c::__vm_enough_memory() for more information.
 839
 840
 841overcommit_ratio
 842================
 843
 844When overcommit_memory is set to 2, the committed address
 845space is not permitted to exceed swap plus this percentage
 846of physical RAM.  See above.
 847
 848
 849page-cluster
 850============
 851
 852page-cluster controls the number of pages up to which consecutive pages
 853are read in from swap in a single attempt. This is the swap counterpart
 854to page cache readahead.
 855The mentioned consecutivity is not in terms of virtual/physical addresses,
 856but consecutive on swap space - that means they were swapped out together.
 857
 858It is a logarithmic value - setting it to zero means "1 page", setting
 859it to 1 means "2 pages", setting it to 2 means "4 pages", etc.
 860Zero disables swap readahead completely.
 861
 862The default value is three (eight pages at a time).  There may be some
 863small benefits in tuning this to a different value if your workload is
 864swap-intensive.
 865
 866Lower values mean lower latencies for initial faults, but at the same time
 867extra faults and I/O delays for following faults if they would have been part of
 868that consecutive pages readahead would have brought in.
 869
 870
 871page_lock_unfairness
 872====================
 873
 874This value determines the number of times that the page lock can be
 875stolen from under a waiter. After the lock is stolen the number of times
 876specified in this file (default is 5), the "fair lock handoff" semantics
 877will apply, and the waiter will only be awakened if the lock can be taken.
 878
 879panic_on_oom
 880============
 881
 882This enables or disables panic on out-of-memory feature.
 883
 884If this is set to 0, the kernel will kill some rogue process,
 885called oom_killer.  Usually, oom_killer can kill rogue processes and
 886system will survive.
 887
 888If this is set to 1, the kernel panics when out-of-memory happens.
 889However, if a process limits using nodes by mempolicy/cpusets,
 890and those nodes become memory exhaustion status, one process
 891may be killed by oom-killer. No panic occurs in this case.
 892Because other nodes' memory may be free. This means system total status
 893may be not fatal yet.
 894
 895If this is set to 2, the kernel panics compulsorily even on the
 896above-mentioned. Even oom happens under memory cgroup, the whole
 897system panics.
 898
 899The default value is 0.
 900
 9011 and 2 are for failover of clustering. Please select either
 902according to your policy of failover.
 903
 904panic_on_oom=2+kdump gives you very strong tool to investigate
 905why oom happens. You can get snapshot.
 906
 907
 908percpu_pagelist_high_fraction
 909=============================
 910
 911This is the fraction of pages in each zone that are can be stored to
 912per-cpu page lists. It is an upper boundary that is divided depending
 913on the number of online CPUs. The min value for this is 8 which means
 914that we do not allow more than 1/8th of pages in each zone to be stored
 915on per-cpu page lists. This entry only changes the value of hot per-cpu
 916page lists. A user can specify a number like 100 to allocate 1/100th of
 917each zone between per-cpu lists.
 918
 919The batch value of each per-cpu page list remains the same regardless of
 920the value of the high fraction so allocation latencies are unaffected.
 921
 922The initial value is zero. Kernel uses this value to set the high pcp->high
 923mark based on the low watermark for the zone and the number of local
 924online CPUs.  If the user writes '0' to this sysctl, it will revert to
 925this default behavior.
 926
 927
 928stat_interval
 929=============
 930
 931The time interval between which vm statistics are updated.  The default
 932is 1 second.
 933
 934
 935stat_refresh
 936============
 937
 938Any read or write (by root only) flushes all the per-cpu vm statistics
 939into their global totals, for more accurate reports when testing
 940e.g. cat /proc/sys/vm/stat_refresh /proc/meminfo
 941
 942As a side-effect, it also checks for negative totals (elsewhere reported
 943as 0) and "fails" with EINVAL if any are found, with a warning in dmesg.
 944(At time of writing, a few stats are known sometimes to be found negative,
 945with no ill effects: errors and warnings on these stats are suppressed.)
 946
 947
 948numa_stat
 949=========
 950
 951This interface allows runtime configuration of numa statistics.
 952
 953When page allocation performance becomes a bottleneck and you can tolerate
 954some possible tool breakage and decreased numa counter precision, you can
 955do::
 956
 957	echo 0 > /proc/sys/vm/numa_stat
 958
 959When page allocation performance is not a bottleneck and you want all
 960tooling to work, you can do::
 961
 962	echo 1 > /proc/sys/vm/numa_stat
 963
 964
 965swappiness
 966==========
 967
 968This control is used to define the rough relative IO cost of swapping
 969and filesystem paging, as a value between 0 and 200. At 100, the VM
 970assumes equal IO cost and will thus apply memory pressure to the page
 971cache and swap-backed pages equally; lower values signify more
 972expensive swap IO, higher values indicates cheaper.
 973
 974Keep in mind that filesystem IO patterns under memory pressure tend to
 975be more efficient than swap's random IO. An optimal value will require
 976experimentation and will also be workload-dependent.
 977
 978The default value is 60.
 979
 980For in-memory swap, like zram or zswap, as well as hybrid setups that
 981have swap on faster devices than the filesystem, values beyond 100 can
 982be considered. For example, if the random IO against the swap device
 983is on average 2x faster than IO from the filesystem, swappiness should
 984be 133 (x + 2x = 200, 2x = 133.33).
 985
 986At 0, the kernel will not initiate swap until the amount of free and
 987file-backed pages is less than the high watermark in a zone.
 988
 989
 990unprivileged_userfaultfd
 991========================
 992
 993This flag controls the mode in which unprivileged users can use the
 994userfaultfd system calls. Set this to 0 to restrict unprivileged users
 995to handle page faults in user mode only. In this case, users without
 996SYS_CAP_PTRACE must pass UFFD_USER_MODE_ONLY in order for userfaultfd to
 997succeed. Prohibiting use of userfaultfd for handling faults from kernel
 998mode may make certain vulnerabilities more difficult to exploit.
 999
1000Set this to 1 to allow unprivileged users to use the userfaultfd system
1001calls without any restrictions.
1002
1003The default value is 0.
1004
1005Another way to control permissions for userfaultfd is to use
1006/dev/userfaultfd instead of userfaultfd(2). See
1007Documentation/admin-guide/mm/userfaultfd.rst.
1008
1009user_reserve_kbytes
1010===================
1011
1012When overcommit_memory is set to 2, "never overcommit" mode, reserve
1013min(3% of current process size, user_reserve_kbytes) of free memory.
1014This is intended to prevent a user from starting a single memory hogging
1015process, such that they cannot recover (kill the hog).
1016
1017user_reserve_kbytes defaults to min(3% of the current process size, 128MB).
1018
1019If this is reduced to zero, then the user will be allowed to allocate
1020all free memory with a single process, minus admin_reserve_kbytes.
1021Any subsequent attempts to execute a command will result in
1022"fork: Cannot allocate memory".
1023
1024Changing this takes effect whenever an application requests memory.
1025
1026
1027vfs_cache_pressure
1028==================
1029
1030This percentage value controls the tendency of the kernel to reclaim
1031the memory which is used for caching of directory and inode objects.
1032
1033At the default value of vfs_cache_pressure=vfs_cache_pressure_denom the kernel
1034will attempt to reclaim dentries and inodes at a "fair" rate with respect to
1035pagecache and swapcache reclaim.  Decreasing vfs_cache_pressure causes the
1036kernel to prefer to retain dentry and inode caches. When vfs_cache_pressure=0,
1037the kernel will never reclaim dentries and inodes due to memory pressure and
1038this can easily lead to out-of-memory conditions. Increasing vfs_cache_pressure
1039beyond vfs_cache_pressure_denom causes the kernel to prefer to reclaim dentries
1040and inodes.
1041
1042Increasing vfs_cache_pressure significantly beyond vfs_cache_pressure_denom may
1043have negative performance impact. Reclaim code needs to take various locks to
1044find freeable directory and inode objects. When vfs_cache_pressure equals
1045(10 * vfs_cache_pressure_denom), it will look for ten times more freeable
1046objects than there are.
1047
1048Note: This setting should always be used together with vfs_cache_pressure_denom.
1049
1050vfs_cache_pressure_denom
1051========================
1052
1053Defaults to 100 (minimum allowed value). Requires corresponding
1054vfs_cache_pressure setting to take effect.
1055
1056watermark_boost_factor
1057======================
1058
1059This factor controls the level of reclaim when memory is being fragmented.
1060It defines the percentage of the high watermark of a zone that will be
1061reclaimed if pages of different mobility are being mixed within pageblocks.
1062The intent is that compaction has less work to do in the future and to
1063increase the success rate of future high-order allocations such as SLUB
1064allocations, THP and hugetlbfs pages.
1065
1066To make it sensible with respect to the watermark_scale_factor
1067parameter, the unit is in fractions of 10,000. The default value of
106815,000 means that up to 150% of the high watermark will be reclaimed in the
1069event of a pageblock being mixed due to fragmentation. The level of reclaim
1070is determined by the number of fragmentation events that occurred in the
1071recent past. If this value is smaller than a pageblock then a pageblocks
1072worth of pages will be reclaimed (e.g.  2MB on 64-bit x86). A boost factor
1073of 0 will disable the feature.
1074
1075
1076watermark_scale_factor
1077======================
1078
1079This factor controls the aggressiveness of kswapd. It defines the
1080amount of memory left in a node/system before kswapd is woken up and
1081how much memory needs to be free before kswapd goes back to sleep.
1082
1083The unit is in fractions of 10,000. The default value of 10 means the
1084distances between watermarks are 0.1% of the available memory in the
1085node/system. The maximum value is 3000, or 30% of memory.
1086
1087A high rate of threads entering direct reclaim (allocstall) or kswapd
1088going to sleep prematurely (kswapd_low_wmark_hit_quickly) can indicate
1089that the number of free pages kswapd maintains for latency reasons is
1090too small for the allocation bursts occurring in the system. This knob
1091can then be used to tune kswapd aggressiveness accordingly.
1092
1093
1094zone_reclaim_mode
1095=================
1096
1097Zone_reclaim_mode allows someone to set more or less aggressive approaches to
1098reclaim memory when a zone runs out of memory. If it is set to zero then no
1099zone reclaim occurs. Allocations will be satisfied from other zones / nodes
1100in the system.
1101
1102This is value OR'ed together of
1103
1104=	===================================
11051	Zone reclaim on
11062	Zone reclaim writes dirty pages out
11074	Zone reclaim swaps pages
1108=	===================================
1109
1110zone_reclaim_mode is disabled by default.  For file servers or workloads
1111that benefit from having their data cached, zone_reclaim_mode should be
1112left disabled as the caching effect is likely to be more important than
1113data locality.
1114
1115Consider enabling one or more zone_reclaim mode bits if it's known that the
1116workload is partitioned such that each partition fits within a NUMA node
1117and that accessing remote memory would cause a measurable performance
1118reduction.  The page allocator will take additional actions before
1119allocating off node pages.
1120
1121Allowing zone reclaim to write out pages stops processes that are
1122writing large amounts of data from dirtying pages on other nodes. Zone
1123reclaim will write out dirty pages if a zone fills up and so effectively
1124throttle the process. This may decrease the performance of a single process
1125since it cannot use all of system memory to buffer the outgoing writes
1126anymore but it preserve the memory on other nodes so that the performance
1127of other processes running on other nodes will not be affected.
1128
1129Allowing regular swap effectively restricts allocations to the local
1130node unless explicitly overridden by memory policies or cpuset
1131configurations.