This is an old revision of the document!
sysctl – get or set kernel state
From the FreeBSD 13.0 manual page:
DESCRIPTION
The sysctl utility retrieves kernel state and allows processes with
appropriate privilege to set kernel state. The state to be retrieved or
set is described using a “Management Information Base” (“MIB”) style
name, described as a dotted set of components.
This description should probably emphasize the valuable information that can be read from sysctls:
hw.ncpu: Number of active CPUs - Often used with for the make(1) -j flag hw.physmem: Amount of physical memory (in bytes) - The physical RAM of the system kstat.zfs.misc.arcstats.size: size - The current size of the ZFS ARC read cache kstat.zfs.misc.arcstats.c_max: c_max - The current maximum size of the ZFS ARC read cache kstat.zfs.misc.arcstats.c_min: c_min - The current minimum size of the ZFS ARC read cache vfs.zfs.arc_max: max arc size (LEGACY) - The writable maximum size (FreeBSD 12 and before) vfs.zfs.arc_min: min arc size (LEGACY) - The writable minimum size (FreeBSD 12 and before) vfs.zfs.arc.max: Max arc size - The writable maximum size (FreeBSD 13 and later) vfs.zfs.arc.min: Min arc size - The writable maximum size (FreeBSD 13 and later)
A list of all available sysctls with descriptions can be produced with:
sysctl -ad kern.ostype: Operating system type kern.osrelease: Operating system release kern.osrevision: Operating system revision ...
The 13,000+ descriptions range in verbosity and consistency.
Proposals for Consistency
As a facility for built-in, developer-facing documentation, the quality of the FreeBSD sysctl descriptions has a direct impact on the FreeBSD developer experience. When authoring a new sysctl description, please consider these guidelines:
Existence
Please do not leave the sysctl -d output blank. Some categories have descriptions while many do not.
vm.domain: vm.domain.0: vm.domain.0.pidctrl: vm.domain.0.pidctrl.kdd: Inverse of derivative gain kstat.zfs: kstat.zfs.zroot: kstat.zfs.zroot.dataset:
A full list of missing descriptions can be obtained with:
grep '[: ]$'
External components like OpenZFS and drivers can be a challenge.
Category Accuracy
hw: hardware hw.machine: Machine class hw.model: Machine model net: Network, (see socket.h) net.local: Local domain net.local.stream: SOCK_STREAM kern.geom.disk: GEOM_DISK stuff kern.geom.disk.ada1: GEOM disk ada1 kern.geom.disk.ada1.flags: Report disk flags vfs.zfs: ZFS file system vfs.zfs.sync_pass_rewrite: Rewrite new bps starting in this pass vfs.zfs.sync_pass_dont_compress: Don't compress starting in this pass
Suggestion: Survey these and propose a format to follow
Suggestion: Do not use “stuff”
Suggestion: Consider manual page references
Provide a summary, not a manual page
hw.dri.debug: Enable debug output, where each bit enables a debug category.
Bit 0 (0x01) will enable CORE messages (drm core code)
Bit 1 (0x02) will enable DRIVER messages (drm controller code)
Bit 2 (0x04) will enable KMS messages (modesetting code)
Bit 3 (0x08) will enable PRIME messages (prime code)
Bit 4 (0x10) will enable ATOMIC messages (atomic code)
Bit 5 (0x20) will enable VBL messages (vblank code)
Bit 7 (0x80) will enable LEASE messages (leasing code)
Bit 8 (0x100) will enable DP messages (displayport code)
hw.ixl.enable_vf_loopback:
Determines mode that embedded device switch will use when SR-IOV is initialized:
0 - Disable (VEPA)
1 - Enable (VEB)
Enabling this will allow VFs in separate VMs to communicate over the hardware bridge.
hw.ixl.i2c_access_method:
I2C access method that driver will use:
0 - best available method
1 - bit bang via I2CPARAMS register
2 - register read/write via I2CCMD register
3 - Use Admin Queue command (best)
machdep.syscall_ret_flush_l1d: Flush L1D on syscall return with error (0 - off, 1 - on, 2 - use hw only, 3 - use sw only
vfs.zfs.vol.mode: Expose as GEOM providers (1), device files (2) or neither
vm.background_launder_max: background laundering cap, in kilobytes
vm.background_launder_rate: background laundering rate, in kilobytes per second
External components can be a challenge. Determine if the output should be fixed upstream or patched.
sysctls with limited options benefit from listing those options.
Providing the input format is helpful.