Contents
Introduction
sysctl, an abbreviation of System Control, is a command 1 and system configuration framework enabling the getting (reading) and setting (modification) 2 of system and kernel state.
sysctl's are defined as key:value pairs, where the key is a .-separated string and namespace, also known as an OID (Object ID), similar to "Management Information Base" ("MIB") style names in SNMP.
The above form effectively enables a tree-like, hierarchically organised set of configuration states.
Example output:
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 the following command
sysctl -ad
Output:
kern.ostype: Operating system type kern.osrelease: Operating system release kern.osrevision: Operating system revision ...
Standards
The quality of sysctl descriptions has a direct impact on the FreeBSD user and system administration experience.
When authoring a new sysctl description, consider these guidelines:
Categorization
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
Ideas:
- Survey these and propose a format to follow
- Suggestion: Do not use "stuff"
- Suggestion: Consider manual page references
Descriptions
sysctl category and items OID descriptions must not be blank.
Example:
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:
sysctl -ad | grep '[: ]$'
External components like OpenZFS and drivers can be a challenge.
Concise but complete and informative
Provide a summary, not a manual page. Avoid line breaks
Example:
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 vm.stats.vm.v_page_size: Page size in bytes
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 unit is helpful such as "in kilobytes per second" or "in bytes" is very helpful.
Descriptive
Descriptions should describe the configuration parameter.
Don't use normal sentences, or end in periods (.).
Example:
kern.random.random_sources: List of active fast entropy sources. kern.random.initial_seeding.disable_bypass_warnings: If non-zero, do not log a warning if the 'bypass_before_seeding' knob is enabled and a request is submitted prior to initial seeding. kern.random.initial_seeding.arc4random_bypassed_before_seeding: If non-zero, the random device was bypassed when initially seeding the kernel arc4random(9), because the 'bypass_before_seeding' knob was enabled and a request was submitted prior to initial seeding. vm.pmap.large_map_pml4_entries: Maximum number of PML4 entries for use by large map (tunable). Each entry corresponds to 512GB of address space.
Suggestion: Rephrase description sentences into "headlines" with units and references as appropriate.
150+ descriptions of 13,000+ end in periods. A full list of descriptions ending in periods can be obtained with:
sysctl -ad | grep '[.]$'
Avoid parser-unfriendly syntax
Avoid characters such as single quotation marks and unnecessary parentheses that may be a challenge to machine parsing:
kern.ps_strings: Location of process' ps_strings structure kern.sched.steal_thresh: Minimum load on remote CPU before we'll steal kern.vt.kbd_reboot: Enable reboot keyboard combination. See kbdmap(5) to configure (typically Ctrl-Alt-Delete)
Other Considerations
Consider a format that includes a brief description, the units, if writable, and a reference:
category.foo.thing: Writable kernel foo count in bytes, writable. See foocount(5)
or
category.foo.thing: Writable kernel foo count - bytes - writable - foocount(5)
Suggestion: Consider a having a goal of generating tabular output with this criteria with a suitable separator.
Suggestion "bytes - writable - foocount(5)": Adding the manual reference is a great improvement. The info to handle correctly an object: type, units, flags, etc., are available in the members of the 'struct sysctl_oid', the sysctl utility allows to retrieve some info via -t -W -T. Furthermore sysutils/nsysctl shows all the properties, in different formats with a specified separator:
% nsysctl -dtFG -s ' - ' hw.snd.report_soft_formats hw.snd.report_soft_formats - report software-emulated formats - integer - I - RD WR RW MPSAFE - 1
% nsysctl -pdtFG -s ", " dev.cpu.0.temperature [NAME]: dev.cpu.0.temperature, [DESCRIPTION]: Current temperature, [TYPE]: integer, [FORMAT]: IK, [FLAGS]: RD DYN MPSAFE, [VALUE]: 46.950006C
% nsysctl -pDg -s ', ' kern.ostype [OID]: 1.1, [NAME]: kern.ostype, [LABEL]: , [DESCRIPTION]: Operating system type, [TYPE]: string, [FORMAT]: A, [FLAGS-RAW]: 2147778560, [FLAGS]: RD MPSAFE CAPRD, [HANDLER]: Defined, [VALUE]: FreeBSD
Do we really need to grow the description string with values from other members of the same struct?