sysctl

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
sysctl [2021/02/11 19:25] – Toning down "Suggestions" MichaelDextersysctl [2021/04/20 01:26] (current) – sysctl descriptions are high impact on everyone, not just devs KubilayKocak
Line 1: Line 1:
-===== sysctl – get or set kernel state =====+===== Introduction =====
  
-From the %%FreeBSD%% 13.0 manual page:+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.
  
-<code> +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. 
-DESCRIPTION + 
-     The sysctl utility retrieves kernel state and allows processes with +The above form effectively enables a tree-like, hierarchically organised set of configuration states.
-     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. +
-</code>+
  
-This description should probably emphasize the valuable information that can be read from sysctls:+Example output:
  
 <code> <code>
Line 25: Line 21:
 </code> </code>
  
-A list of all available sysctls with descriptions can be produced with:+A list of all available sysctls with descriptions can be produced with the following command
  
 <code> <code>
 sysctl -ad sysctl -ad
 +</code>
  
 +Output:
 +
 +<code>
 kern.ostype: Operating system type kern.ostype: Operating system type
 kern.osrelease: Operating system release kern.osrelease: Operating system release
 kern.osrevision: Operating system revision kern.osrevision: Operating system revision
 ... ...
- 
 </code> </code>
  
-The 13,000+ descriptions range in verbosity and consistency.+===== Standards =====
  
-==== Proposals for Consistency ====+The quality of sysctl descriptions has a direct impact on the %%FreeBSD%% user and system administration experience.
  
-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:+When authoring a new sysctl description, consider these guidelines:
  
-=== Existence === +==== Categorization ====
- +
-Please do not leave the sysctl -d output blank. Some categories have descriptions while many do not. +
- +
-<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. +
- +
-=== Category Accuracy ===+
  
 <code> <code>
Line 86: Line 62:
 </code> </code>
  
-Suggestion: Survey these and propose a format to follow+Ideas:
  
-Suggestion: Do not use "stuff"+  * Survey these and propose a format to follow 
 +  * Suggestion: Do not use "stuff" 
 +  * Suggestion: Consider manual page references
  
-Suggestion: Consider manual page references+==== Descriptions ====
  
-=== Provide a summary, not a manual page/avoid line breaks ===+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> <code>
Line 105: Line 110:
                 Bit 8 (0x100) will enable DP messages (displayport code)                 Bit 8 (0x100) will enable DP messages (displayport code)
  
-hw.ixl.enable_vf_loopback: +hw.ixl.enable_vf_loopback:
 Determines mode that embedded device switch will use when SR-IOV is initialized: Determines mode that embedded device switch will use when SR-IOV is initialized:
         0 - Disable (VEPA)         0 - Disable (VEPA)
Line 111: Line 116:
 Enabling this will allow VFs in separate VMs to communicate over the hardware bridge. Enabling this will allow VFs in separate VMs to communicate over the hardware bridge.
  
-hw.ixl.i2c_access_method: +hw.ixl.i2c_access_method:
 I2C access method that driver will use: I2C access method that driver will use:
         0 - best available method         0 - best available method
Line 134: Line 139:
 Providing the input unit is helpful such as "in kilobytes per second" or "in bytes" is very helpful. Providing the input unit is helpful such as "in kilobytes per second" or "in bytes" is very helpful.
  
-=== Use descriptions, not sentences ending in periods ===+=== Descriptive === 
 + 
 +Descriptions should //describe// the configuration parameter. 
 + 
 +Don't use normal sentences, or end in periods (.). 
 + 
 +Example:
  
 <code> <code>
Line 152: Line 163:
 </code> </code>
  
-=== Avoid syntax that may be parser-unfriendly ===+=== Avoid parser-unfriendly syntax ===
  
-Consider avoiding characters such as single quotation marks and unnecessary parentheses that may be a challenge to machine parsing:+Avoid characters such as single quotation marks and unnecessary parentheses that may be a challenge to machine parsing:
  
 <code> <code>
Line 164: Line 175:
 </code> </code>
  
-==== Possible Considerations ====+==== Other Considerations ====
  
 Consider a format that includes a brief description, the units, if writable, and a reference: Consider a format that includes a brief description, the units, if writable, and a reference:
Line 180: Line 191:
 Suggestion: Consider a having a goal of generating tabular output with this criteria with a suitable separator. Suggestion: Consider a having a goal of generating tabular output with this criteria with a suitable separator.
  
-Suggestion: new kernel build option SYSCTL_IMPL_DESC, if it is enabled add _ _FILE_ _ to the description to know the entry point/implementation file of the object. This proposal needs a cost benefit analysis; possible implementation: sysctl(9) macros or raw SYSCTL_OID().+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 =====
  
  • sysctl.1613071559.txt.gz
  • Last modified: 2021/02/11 19:25
  • by MichaelDexter