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/04/19 04:46] – Add footnotes section separator at article tail, fix code block KubilayKocaksysctl [2021/04/20 01:26] (current) – sysctl descriptions are high impact on everyone, not just devs KubilayKocak
Line 1: Line 1:
-===== sysctl – system control framework =====+===== 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, 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.
Line 36: Line 36:
 </code> </code>
  
-==== Proposals for Consistency ====+===== Standards =====
  
-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:+The quality of sysctl descriptions has a direct impact on the %%FreeBSD%% user and system administration experience.
  
-=== Existence ===+When authoring a new sysctl description, consider these guidelines:
  
-Please do not leave the sysctl -d output blank. Some categories have descriptions while many do not. +==== Categorization ====
- +
-<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 83: 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 131: 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 149: 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 161: 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:
  • sysctl.1618807608.txt.gz
  • Last modified: 2021/04/19 04:46
  • by KubilayKocak