This is an old revision of the document!


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.

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.

  • sysctl.1612979619.txt.gz
  • Last modified: 2021/02/10 17:53
  • by MichaelDexter