path: root/Documentation/admin-guide/sysctl/kernel.rst

===================================
Documentation for /proc/sys/kernel/
===================================

.. See scripts/check-sysctl-docs to keep this up to date


Copyright (c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>

Copyright (c) 2009,        Shen Feng<shen@cn.fujitsu.com>

For general info and legal blurb, please look in :doc:`index`.

------------------------------------------------------------------------------

This file contains documentation for the sysctl files in
``/proc/sys/kernel/`` and is valid for Linux kernel version 2.2.

The files in this directory can be used to tune and monitor
miscellaneous and general things in the operation of the Linux
kernel. Since some of the files *can* be used to screw up your
system, it is advisable to read both documentation and source
before actually making adjustments.

Currently, these files might (depending on your configuration)
show up in ``/proc/sys/kernel``:

.. contents:: :local:


acct
====

::

    highwater lowwater frequency

If BSD-style process accounting is enabled these values control
its behaviour. If free space on filesystem where the log lives
goes below ``lowwater``% accounting suspends. If free space gets
above ``highwater``% accounting resumes. ``frequency`` determines
how often do we check the amount of free space (value is in
seconds). Default:

::

    4 2 30

That is, suspend accounting if free space drops below 2%; resume it
if it increases to at least 4%; consider information about amount of
free space valid for 30 seconds.


acpi_video_flags
================

See :doc:`/power/video`. This allows the video resume mode to be set,
in a similar fashion to the ``acpi_sleep`` kernel parameter, by
combining the following values:

= =======
1 s3_bios
2 s3_mode
4 s3_beep
= =======


auto_msgmni
===========

This variable has no effect and may be removed in future kernel
releases. Reading it always returns 0.
Up to Linux 3.17, it enabled/disabled automatic recomputing of
`msgmni`_
upon memory add/remove or upon IPC namespace creation/removal.
Echoing "1" into this file enabled msgmni automatic recomputing.
Echoing "0" turned it off. The default value was 1.


bootloader_type (x86 only)
==========================

This gives the bootloader type number as indicated by the bootloader,
shifted left by 4, and OR'd with the low four bits of the bootloader
version.  The reason for this encoding is that this used to match the
``type_of_loader`` field in the kernel header; the encoding is kept for
backwards compatibility.  That is, if the full bootloader type number
is 0x15 and the full version number is 0x234, this file will contain
the value 340 = 0x154.

See the ``type_of_loader`` and ``ext_loader_type`` fields in
:doc:`/x86/boot` for additional information.


bootloader_version (x86 only)
=============================

The complete bootloader version number.  In the example above, this
file will contain the value 564 = 0x234.

See the ``type_of_loader`` and ``ext_loader_ver`` fields in
:doc:`/x86/boot` for additional information.


cap_last_cap
============

Highest valid capability of the running kernel.  Exports
``CAP_LAST_CAP`` from the kernel.


core_pattern
============

``core_pattern`` is used to specify a core dumpfile pattern name.

* max length 127 characters; default value is "core"
* ``core_pattern`` is used as a pattern template for the output
  filename; certain string patterns (beginning with '%') are
  substituted with their actual values.
* backward compatibility with ``core_uses_pid``:

	If ``core_pattern`` does not include "%p" (default does not)
	and ``core_uses_pid`` is set, then .PID will be appended to
	the filename.

* corename format specifiers

	========	==========================================
	%<NUL>		'%' is dropped
	%%		output one '%'
	%p		pid
	%P		global pid (init PID namespace)
	%i		tid
	%I		global tid (init PID namespace)
	%u		uid (in initial user namespace)
	%g		gid (in initial user namespace)
	%d		dump mode, matches ``PR_SET_DUMPABLE`` and
			``/proc/sys/fs/suid_dumpable``
	%s		signal number
	%t		UNIX time of dump
	%h		hostname
	%e		executable filename (may be shortened)
	%E		executable path
	%c		maximum size of core file by resource limit RLIMIT_CORE
	%<OTHER>	both are dropped
	========	==========================================

* If the first character of the pattern is a '|', the kernel will treat
  the rest of the pattern as a command to run.  The core dump will be
  written to the standard input of that program instead of to a file.


core_pipe_limit
===============

This sysctl is only applicable when `core_pattern`_ is configured to
pipe core files to a user space helper (when the first character of
``core_pattern`` is a '|', see above).
When collecting cores via a pipe to an application, it is occasionally
useful for the collecting application to gather data about the
crashing process from its ``/proc/pid`` directory.
In order to do this safely, the kernel must wait for the collecting
process to exit, so as not to remove the crashing processes proc files
prematurely.
This in turn creates the possibility that a misbehaving userspace
collecting process can block the reaping of a crashed process simply
by never exiting.
This sysctl defends against that.
It defines how many concurrent crashing processes may be piped to user
space applications in parallel.
If this value is exceeded, then those crashing processes above that
value are noted via the kernel log and their cores are skipped.
0 is a special value, indicating that unlimited processes may be
captured in parallel, but that no waiting will take place (i.e. the
collecting process is not guaranteed access to ``/proc/<crashing
pid>/``).
This value defaults to 0.


core_uses_pid
=============

The default coredump filename is "core".  By setting
``core_uses_pid`` to 1, the coredump filename becomes core.PID.
If `core_pattern`_ does not include "%p" (default does not)
and ``core_uses_pid`` is set, then .PID will be appended to
the filename.


ctrl-alt-del
============

When the value in this file is 0, ctrl-alt-del is trapped and
sent to the ``init(1)`` program to handle a graceful restart.
When, however, the value is > 0, Linux's reaction to a Vulcan
Nerve Pinch (tm) will be an immediate reboot, without even
syncing its dirty buffers.

Note:
  when a program (like dosemu) has the keyboard in 'raw'
  mode, the ctrl-alt-del is intercepted by the program before it
  ever reaches the kernel tty layer, and it's up to the program
  to decide what to do with it.


dmesg_restrict
==============

This toggle indicates whether unprivileged users are prevented
from using ``dmesg(8)`` to view messages from the kernel's log
buffer.
When ``dmesg_restrict`` is set to 0 there are no restrictions.
When ``dmesg_restrict`` is set set to 1, users must have
``CAP_SYSLOG`` to use ``dmesg(8)``.

The kernel config option ``CONFIG_SECURITY_DMESG_RESTRICT`` sets the
default value of ``dmesg_restrict``.


domainname & hostname
=====================

These files can be used to set the NIS/YP domainname and the
hostname of your box in exactly the same way as the commands
domainname and hostname, i.e.::

	# echo "darkstar" > /proc/sys/kernel/hostname
	# echo "mydomain" > /proc/sys/kernel/domainname

has the same effect as::

	# hostname "darkstar"
	# domainname "mydomain"

Note, however, that the classic darkstar.frop.org has the
hostname "darkstar" and DNS (Internet Domain Name Server)
domainname "frop.org", not to be confused with the NIS (Network
Information Service) or YP (Yellow Pages) domainname. These two
domain names are in general different. For a detailed discussion
see the ``hostname(1)`` man page.


hardlockup_all_cpu_backtrace
============================

This value controls the hard lockup detector behavior when a hard
lockup condition is detected as to whether or not to gather further
debug information. If enabled, arch-specific all-CPU stack dumping
will be initiated.

= ============================================
0 Do nothing. This is the default behavior.
1 On detection capture more debug information.
= ============================================


hardlockup_panic
================

This parameter can be used to control whether the kernel panics
when a hard lockup is detected.

= ===========================
0 Don't panic on hard lockup.
1 Panic on hard lockup.
= ===========================

See :doc:`/admin-guide/lockup-watchdogs` for more information.
This can also be set using the nmi_watchdog kernel parameter.


hotplug
=======

Path for the hotplug policy agent.
Default value is "``/sbin/hotplug``".


hung_task_panic
===============

Controls the kernel's behavior when a hung task is detected.
This file shows up if ``CONFIG_DETECT_HUNG_TASK`` is enabled.

= =================================================
0 Continue operation. This is the default behavior.
1 Panic immediately.
= =================================================


hung_task_check_count
=====================

The upper bound on the number of tasks that are checked.
This file shows up if ``CONFIG_DETECT_HUNG_TASK`` is enabled.


hung_task_timeout_secs
======================

When a task in D state did not get scheduled
for more than this value report a warning.
This file shows up if ``CONFIG_DETECT_HUNG_TASK`` is enabled.

0 means infinite timeout, no checking is done.

Possible values to set are in range {0:``LONG_MAX``/``HZ``}.


hung_task_check_interval_secs
=============================

Hung task check interval. If hung task checking is enabled
(see `hung_task_timeout_secs`_), the check is done every
``hung_task_check_interval_secs`` seconds.
This file shows up if ``CONFIG_DETECT_HUNG_TASK`` is enabled.

0 (default) means use ``hung_task_timeout_secs`` as checking
interval.

Possible values to set are in range {0:``LONG_MAX``/``HZ``}.


hung_task_warnings
==================

The maximum number of warnings to report. During a check interval
if a hung task is detected, this value is decreased by 1.
When this value reaches 0, no more warnings will be reported.
This file shows up if ``CONFIG_DETECT_HUNG_TASK`` is enabled.

-1: report an infinite number of warnings.


hyperv_record_panic_msg
=======================

Controls whether the panic kmsg data should be reported to Hyper-V.

= =========================================================
0 Do not report panic kmsg data.
1 Report the panic kmsg data. This is the default behavior.
= =========================================================


kexec_load_disabled
===================

A toggle indicating if the ``kexec_load`` syscall has been disabled.
This value defaults to 0 (false: ``kexec_load`` enabled), but can be
set to 1 (true: ``kexec_load`` disabled).
Once true, kexec can no longer be used, and the toggle cannot be set
back to false.
This allows a kexec image to be loaded before disabling the syscall,
allowing a system to set up (and later use) an image without it being
altered.
Generally used together with the `modules_disabled`_ sysctl.


kptr_restrict
=============

This toggle indicates whether restrictions are placed on
exposing kernel addresses via ``/proc`` and other interfaces.

When ``kptr_restrict`` is set to 0 (the default) the address is hashed
before printing.
(This is the equivalent to %p.)

When ``kptr_restrict`` is set to 1, kernel pointers printed using the
%pK format specifier will be replaced with 0s unless the user has
``CAP_SYSLOG`` and effective user and group ids are equal to the real
ids.
This is because %pK checks are done at read() time rather than open()
time, so if permissions are elevated between the open() and the read()
(e.g via a setuid binary) then %pK will not leak kernel pointers to
unprivileged users.
Note, this is a temporary solution only.
The correct long-term solution is to do the permission checks at
open() time.
Consider removing world read permissions from files that use %pK, and
using `dmesg_restrict`_ to protect against uses of %pK in ``dmesg(8)``
if leaking kernel pointer values to unprivileged users is a concern.

When ``kptr_restrict`` is set to 2, kernel pointers printed using
%pK will be replaced with 0s regardless of privileges.


modprobe
========

This gives the full path of the modprobe command which the kernel will
use to load modules. This can be used to debug module loading
requests::

    echo '#! /bin/sh' > /tmp/modprobe
    echo 'echo "$@" >> /tmp/modprobe.log' >> /tmp/modprobe
    echo 'exec /sbin/modprobe "$@"' >> /tmp/modprobe
    chmod a+x /tmp/modprobe
    echo /tmp/modprobe > /proc/sys/kernel/modprobe

This only applies when the *kernel* is requesting that the module be
loaded; it won't have any effect if the module is being loaded
explicitly using ``modprobe`` from userspace.


modules_disabled
================

A toggle value indicating if modules are allowed to be loaded
in an otherwise modular kernel.  This toggle defaults to off
(0), but can be set true (1).  Once true, modules can be
neither loaded nor unloaded, and the toggle cannot be set back
to false.  Generally used with the `kexec_load_disabled`_ toggle.


.. _msgmni:

msgmax, msgmnb, and msgmni
==========================

``msgmax`` is the maximum size of an IPC message, in bytes. 8192 by
default (``MSGMAX``).

``msgmnb`` is the maximum size of an IPC queue, in bytes. 16384 by
default (``MSGMNB``).

``msgmni`` is the maximum number of IPC queues. 32000 by default
(``MSGMNI``).


msg_next_id, sem_next_id, and shm_next_id (System V IPC)
========================================================

These three toggles allows to specify desired id for next allocated IPC
object: message, semaphore or shared memory respectively.

By default they are equal to -1, which means generic allocation logic.
Possible values to set are in range {0:``INT_MAX``}.

Notes:
  1) kernel doesn't guarantee, that new object will have desired id. So,
     it's up to userspace, how to handle an object with "wrong" id.
  2) Toggle with non-default value will be set back to -1 by kernel after
     successful IPC object allocation. If an IPC object allocation syscall
     fails, it is undefined if the value remains unmodified or is reset to -1.

modprobe:
=========

The path to the usermode helper for autoloading kernel modules, by
default "/sbin/modprobe".  This binary is executed when the kernel
requests a module.  For example, if userspace passes an unknown
filesystem type to mount(), then the kernel will automatically request
the corresponding filesystem module by executing this usermode helper.
This usermode helper should insert the needed module into the kernel.

This sysctl only affects module autoloading.  It has no effect on the
ability to explicitly insert modules.

If this sysctl is set to the empty string, then module autoloading is
completely disabled.  The kernel will not try to execute a usermode
helper at all, nor will it call the kernel_module_request LSM hook.

If CONFIG_STATIC_USERMODEHELPER=y is set in the kernel configuration,
then the configured static usermode helper overrides this sysctl,
except that the empty string is still accepted to completely disable
module autoloading as described above.

nmi_watchdog
============

This parameter can be used to control the NMI watchdog
(i.e. the hard lockup detector) on x86 systems.

= =================================
0 Disable the hard lockup detector.
1 Enable the hard lockup detector.
= =================================

The hard lockup detector monitors each CPU for its ability to respond to
timer interrupts. The mechanism utilizes CPU performance counter registers
that are programmed to generate Non-Maskable Interrupts (NMIs) periodically
while a CPU is busy. Hence, the alternative name 'NMI watchdog'.

The NMI watchdog is disabled by default if the kernel is running as a guest
in a KVM virtual machine. This default can be overridden by adding::

   nmi_watchdog=1

to the guest kernel command line (see :doc:`/admin-guide/kernel-parameters`).


numa_balancing
==============

Enables/disables automatic page fault based NUMA memory
balancing. Memory is moved automatically to nodes
that access it often.

Enables/disables automatic NUMA memory balancing. On NUMA machines, there
is a performance penalty if remote memory is accessed by a CPU. When this
feature is enabled the kernel samples what task thread is accessing memory
by periodically unmapping pages and later trapping a page fault. At the
time of the page fault, it is determined if the data being accessed should
be migrated to a local memory node.

The unmapping of pages and trapping faults incur additional overhead that
ideally is offset by improved memory locality but there is no universal
guarantee. If the target workload is already bound to NUMA nodes then this
feature should be disabled. Otherwise, if the system overhead from the
feature is too high then the rate the kernel samples for NUMA hinting
faults may be controlled by the `numa_balancing_scan_period_min_ms,
numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms,
numa_balancing_scan_size_mb`_, and numa_balancing_settle_count sysctls.


numa_balancing_scan_period_min_ms, numa_balancing_scan_delay_ms, numa_balancing_scan_period_max_ms, numa_balancing_scan_size_mb
===============================================================================================================================


Automatic NUMA balancing scans tasks address space and unmaps pages to
detect if pages are properly placed or if the data should be migrated to a
memory node local to where the task is running.  Every "scan delay" the task
scans the next "scan size" number of pages in its address space. When the
end of the address s