===== Introduction =====

sysctl, an abbreviation of //System Control//, is a command (([[https://man.freebsd.org/sysctl/8)|sysctl(8)]] manual page)) and system configuration framework enabling the getting (reading) and setting (modification) ((Some sysctl OID's are read-only at runtime, or require modification at the boot loader (''%%/boot/loader.conf%%'') stage)) 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:

<code>
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)
</code>

A list of all available sysctls with descriptions can be produced with the following command

<code>
sysctl -ad
</code>

Output:

<code>
kern.ostype: Operating system type
kern.osrelease: Operating system release
kern.osrevision: Operating system revision
...
</code>

===== 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 ====

<code>
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
</code>

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:

<code>
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:
</code>

A full list of missing descriptions can be obtained with:

<code>
sysctl -ad | grep '[: ]$'
</code>

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:

<code>
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
</code>

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:

<code>
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.
</code>

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:

<code>
sysctl -ad | grep '[.]$'
</code>

=== Avoid parser-unfriendly syntax ===

Avoid characters such as single quotation marks and unnecessary parentheses that may be a challenge to machine parsing:

<code>
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)
</code>

==== Other Considerations ====

Consider a format that includes a brief description, the units, if writable, and a reference:

<code>
category.foo.thing: Writable kernel foo count in bytes, writable. See foocount(5)
</code>

or

<code>
category.foo.thing: Writable kernel foo count - bytes - writable - foocount(5)
</code>

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:

<code>
% nsysctl -dtFG -s ' - ' hw.snd.report_soft_formats
hw.snd.report_soft_formats - report software-emulated formats - integer - I -  RD WR RW MPSAFE - 1
</code>

<code>
% 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
</code>

<code>
% 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
</code>

Do we really need to grow the description string with values from other members of the same struct?

===== Footnotes =====