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:40] – Provide non (manpage) duplicative intro KubilayKocaksysctl [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 =====
  
-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) <<FootNote(Some sysctl OID's are read-only at runtime, or require modification at the boot loader (+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.
-/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.
- +
-The above form effectively enables' a tree-like, hierarchically organised set of configuration states.+
  
 Example output: Example output:
  
-{{{+<code>
 hw.ncpu: Number of active CPUs - Often used with for the make(1) -j flag 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 hw.physmem: Amount of physical memory (in bytes) - The physical RAM of the system
Line 39: 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 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 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 198: Line 209:
  
 Do we really need to grow the description string with values from other members of the same struct? Do we really need to grow the description string with values from other members of the same struct?
 +
 +===== Footnotes =====
  
  • sysctl.1618807209.txt.gz
  • Last modified: 2021/04/19 04:40
  • by KubilayKocak