1.\" $NetBSD: sysctl.8,v 1.162 2011/08/03 01:47:40 christos Exp $ 2.\" 3.\" Copyright (c) 2004 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" 28.\" Copyright (c) 1993 29.\" The Regents of the University of California. All rights reserved. 30.\" 31.\" Redistribution and use in source and binary forms, with or without 32.\" modification, are permitted provided that the following conditions 33.\" are met: 34.\" 1. Redistributions of source code must retain the above copyright 35.\" notice, this list of conditions and the following disclaimer. 36.\" 2. Redistributions in binary form must reproduce the above copyright 37.\" notice, this list of conditions and the following disclaimer in the 38.\" documentation and/or other materials provided with the distribution. 39.\" 3. Neither the name of the University nor the names of its contributors 40.\" may be used to endorse or promote products derived from this software 41.\" without specific prior written permission. 42.\" 43.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 44.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 45.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 46.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 47.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 48.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 49.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 51.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 52.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 53.\" SUCH DAMAGE. 54.\" 55.\" @(#)sysctl.8 8.1 (Berkeley) 6/6/93 56.\" 57.Dd August 2, 2011 58.Dt SYSCTL 8 59.Os 60.Sh NAME 61.Nm sysctl 62.Nd get or set kernel state 63.Sh SYNOPSIS 64.Nm sysctl 65.Op Fl AdeMnq 66.Oo 67.Fl r | 68.Fl x 69.Oc 70.Op Ar name ... 71.Nm sysctl 72.Op Fl nq 73.Oo 74.Fl r | 75.Fl x 76.Oc 77.Fl w 78.Ar name Ns Li [?]= Ns Ar value ... 79.Nm sysctl 80.Op Fl en 81.Oo 82.Fl r | 83.Fl x 84.Oc 85.Fl a 86.Nm sysctl 87.Op Fl nq 88.Oo 89.Fl r | 90.Fl x 91.Oc 92.Fl f 93.Ar file 94.Sh DESCRIPTION 95The 96.Nm sysctl 97utility retrieves kernel state and allows processes with 98appropriate privilege to set kernel state. 99The state to be retrieved or set is described using a 100``Management Information Base'' (``MIB'') style name, 101described as a dotted set of components. 102The 103.Sq / 104character may also be used as a separator and a leading separator 105character is accepted. 106If 107.Ar name 108specifies a non-leaf node in the MIB, all the nodes underneath 109.Ar name 110will be printed. 111.Pp 112The following options are available: 113.Bl -tag -width indent 114.It Fl A 115List all the known MIB names including tables, unless any MIB 116arguments or 117.Fl f Ar file 118are given. 119Those with string or integer values will be printed as with the 120.Fl a 121flag; for table or structure values that 122.Nm 123is not able to print, 124the name of the utility to retrieve them is given. 125Errors in retrieving or setting values will be directed to stdout 126instead of stderr. 127.It Fl a 128List all the currently available string or integer values. 129The use of a solitary separator character (either 130.Sq \&. 131or 132.Sq / ) 133by 134itself has the same effect. 135Any given 136.Ar name 137arguments are ignored if this option is specified. 138.It Fl d 139Descriptions of each of the nodes selected will be printed instead of 140their values. 141.It Fl e 142Separate the name and the value of the variable(s) with 143.Ql = . 144This is useful for producing output which can be fed back to the 145.Nm 146utility. 147This option is ignored if 148.Fl n 149is specified or a variable is being set. 150.It Fl f 151Specifies the name of a file to read and process. 152Blank lines and comments (beginning with 153.Ql # ) 154are ignored. 155Line continuations with 156.Ql \e 157are permitted. 158Remaining lines are processed similarly to 159command line arguments of the form 160.Ar name 161or 162.Ar name Ns Li = Ns Ar value . 163The 164.Fl w 165flag is implied by 166.Fl f . 167Any 168.Ar name 169arguments are ignored. 170.It Fl M 171Makes 172.Nm 173print the MIB instead of any of the actual values contained in the 174MIB. 175This causes the entire MIB to be printed unless specific MIB arguments 176or 177.Fl f Ar file 178are also given. 179.It Fl n 180Specifies that the printing of the field name should be 181suppressed and that only its value should be output. 182This flag is useful for setting shell variables. 183For example, to save the pagesize in variable psize, use: 184.Bd -literal -offset indent -compact 185set psize=`sysctl -n hw.pagesize` 186.Ed 187.It Fl q 188Used to indicate that nothing should be printed for reads or writes unless an 189error is detected. 190For reads, not finding a variable does not print an error, but exits with 191an error code. 192This is useful just for testing that a variable exists. 193.It Fl r 194Raw output form. 195Values printed are in their raw binary forms as retrieved directly 196from the kernel. 197Some additional nodes that 198.Nm 199cannot print directly can be retrieved with this flag. 200This option conflicts with the 201.Fl x 202option. 203.It Fl w 204Sets the MIB style name given to the value given. 205The MIB style name and value must be separated by 206.Ql = 207with no whitespace. 208To prevent an error if the MIB style name does not exist (as would be the 209case with optional kernel components), one can separate the MIB style name 210and the value with 211.Ql ?= . 212Only integral and string values can be set via this method. 213.It Fl x 214Makes 215.Nm 216print the requested value in a hexadecimal representation instead of 217its regular form. 218If specified more than once, the output for each value resembles that of 219.Xr hexdump 1 220when given the 221.Fl C 222flag. 223This option conflicts with the 224.Fl r 225option. 226.Pp 227.El 228The 229.Ql proc 230top-level MIB has a special semantic: it represent per-process values 231and as such may differ from one process to another. 232The second-level name is the pid of the process (in decimal form), 233or the special word 234.Ql curproc . 235For variables below 236.Ql proc. Ns Ao pid Ac Ns .rlimit , 237the integer value may be replaced 238with the string 239.Ql unlimited 240if it matches the magic value used to disable 241a limit. 242.Pp 243The information available from 244.Nm sysctl 245consists of integers, strings, and tables. 246The tabular information can only be retrieved by special 247purpose programs such as 248.Nm ps , 249.Nm systat , 250and 251.Nm netstat . 252See 253.Xr sysctl 7 254for description of available MIBs. 255.Sh CREATION AND DELETION 256New nodes are allowed to be created by the superuser when the kernel 257is running at security level 0. 258These new nodes may refer to existing kernel data or to new data that 259is only instrumented by 260.Xr sysctl 3 261itself. 262.Pp 263The syntax for creating new nodes is 264.Dq //create=new.node.path 265followed by one or more of the following attributes separated by 266commas. 267The use of a double separator (both 268.Sq / 269and 270.Sq \&. 271can be used as 272separators) as the prefix tells sysctl that the first series of tokens 273is not a MIB name, but a command. 274It is recommended that the double separator preceding the command not 275be the same as the separator used in naming the MIB entry so as to 276avoid possible parse conflicts. 277The 278.Dq value 279assigned, if one is given, must be last. 280.Pp 281.Bl -bullet -compact 282.It 283.Ar type= Ns Aq Ar T 284where 285.Ar T 286must be one of 287.Dq node , 288.Dq int , 289.Dq string , 290.Dq quad , 291or 292.Dq struct . 293If the type is omitted, the 294.Dq node 295type is assumed. 296.It 297.Ar size= Ns Aq Ar S 298here, 299.Ar S 300asserts the size of the new node. 301Nodes of type 302.Dq node 303should not have a size set. 304The size may be omitted for nodes of types 305.Dq int 306or 307.Dq quad . 308If the size is omitted for a node of type 309.Dq string , 310the size will be determined by the length of the given value, or by 311the kernel for kernel strings. 312Nodes of type 313.Dq struct 314must have their size explicitly set. 315.It 316.Ar addr= Ns Aq Ar A 317or 318.Ar symbol= Ns Aq Ar A 319The kernel address of the data being instrumented. 320If 321.Dq symbol 322is used, the symbol must be globally visible to the in-kernel 323.Xr ksyms 4 324driver. 325.It 326.Ar n= Ns Aq Ar N 327The MIB number to be assigned to the new node. 328If no number is specified, the kernel will assign a value. 329.It 330.Ar flags= Ns Aq Ar F 331A concatenated string of single letters that govern the behavior of 332the node. 333Flags currently available are: 334.Bl -tag -width www 335.It a 336Allow anyone to write to the node, if it is writable. 337.It h 338.Dq Hidden . 339.Nm 340must be invoked with 341.Fl A 342or the hidden node must be specifically requested in order to see it 343.It i 344.Dq Immediate . 345Makes the node store data in itself, rather than allocating new space 346for it. 347This is the default for nodes of type 348.Dq int 349and 350.Dq quad . 351This is the opposite of owning data. 352.It o 353.Dq Own . 354When the node is created, separate space will be allocated to store 355the data to be instrumented. 356This is the default for nodes of type 357.Dq string 358and 359.Dq struct 360where it is not possible to guarantee sufficient space to store the 361data in the node itself. 362.It p 363.Dq Private . 364Nodes that are marked private, and children of nodes so marked, are 365only viewable by the superuser. 366Be aware that the immediate data that some nodes may store is not 367necessarily protected by this. 368.It x 369.Dq Hexadecimal . 370Make 371.Nm 372default to hexadecimal display of the retrieved value 373.It r 374.Dq Read-only . 375The data instrumented by the given node is read-only. 376Note that other mechanisms may still exist for changing the data. 377This is the default for nodes that instrument data. 378.It w 379.Dq Writable . 380The data instrumented by the given node is writable at any time. 381This is the default for nodes that can have children. 382.El 383.Pp 384.It 385.Ar value= Ns Aq Ar V 386An initial starting value for a new node that does not reference 387existing kernel data. 388Initial values can only be assigned for nodes of the 389.Dq int , 390.Dq quad , 391and 392.Dq string 393types. 394.El 395.Pp 396New nodes must fit the following set of criteria: 397.Pp 398.Bl -bullet -compact 399.It 400If the new node is to address an existing kernel object, only one of the 401.Dq symbol 402or 403.Dq addr 404arguments may be given. 405.It 406The size for a 407.Dq struct 408type node must be specified; no initial value is expected or permitted. 409.It 410Either the size or the initial value for a 411.Dq string 412node must be given. 413.It 414The node which will be the parent of the new node must be writable. 415.El 416.Pp 417If any of the given parameters describes an invalid configuration, 418.Nm 419will emit a diagnostic message to the standard error and exit. 420.Pp 421Descriptions can be added by the super-user to any node that does not 422have one, provided that the node is not marked with the 423.Dq PERMANENT 424flag. 425The syntax is similar to the syntax for creating new nodes with the 426exception of the keyword that follows the double separator at the 427start of the command: 428.Dq //describe=new.node.path=new node description . 429Once a description has been added, it cannot be changed or removed. 430.Pp 431When destroying nodes, only the path to the node is necessary, i.e., 432.Dq //destroy=old.node.path . 433No other parameters are expected or permitted. 434Nodes being destroyed must have no children, and their parent must be 435writable. 436Nodes that are marked with the 437.Dq Dv PERMANENT 438flag (as assigned by the kernel) may not be deleted. 439.Pp 440In all cases, the initial 441.Sq = 442that follows the command (eg, 443.Dq create , 444.Dq destroy , 445or 446.Dq describe ) 447may be replaced with another instance of the separator character, 448provided that the same separator character is used for the length of 449the name specification. 450.Sh FILES 451.Bl -tag -width /etc/sysctl.conf -compact 452.It Pa /etc/sysctl.conf 453.Nm 454variables set at boot time 455.El 456.Sh EXAMPLES 457For example, to retrieve the maximum number of processes allowed 458in the system, one would use the following request: 459.Bd -literal -offset indent -compact 460sysctl kern.maxproc 461.Ed 462.Pp 463To set the maximum number of processes allowed 464in the system to 1000, one would use the following request: 465.Bd -literal -offset indent -compact 466sysctl -w kern.maxproc=1000 467.Ed 468.Pp 469Information about the system clock rate may be obtained with: 470.Bd -literal -offset indent -compact 471sysctl kern.clockrate 472.Ed 473.Pp 474Information about the load average history may be obtained with: 475.Bd -literal -offset indent -compact 476sysctl vm.loadavg 477.Ed 478.Pp 479To view the values of the per-process variables of the current shell, 480the request: 481.Bd -literal -offset indent -compact 482sysctl proc.$$ 483.Ed 484can be used if the shell interpreter replaces $$ with its pid (this is true 485for most shells). 486.Pp 487To redirect core dumps to the 488.Pa /var/tmp/ Ns Aq username 489directory, 490.Bd -literal -offset indent -compact 491sysctl -w proc.$$.corename=/var/tmp/%u/%n.core 492.Ed 493should be used. 494.Bd -literal -offset indent -compact 495sysctl -w proc.curproc.corename=/var/tmp/%u/%n.core 496.Ed 497changes the value for the sysctl process itself, and will not have the desired 498effect. 499.Pp 500To create the root of a new sub-tree called 501.Dq local 502add some children to the new node, and some descriptions: 503.Bd -literal -offset indent -compact 504sysctl -w //create=local 505sysctl -w //describe=local=my local sysctl tree 506sysctl -w //create=local.esm_debug,type=int,symbol=esm_debug,flags=w 507sysctl -w //describe=local.esm_debug=esm driver debug knob 508sysctl -w //create=local.audiodebug,type=int,symbol=audiodebug,flags=w 509sysctl -w //describe=local.audiodebug=generic audio debug knob 510.Ed 511Note that the children are made writable so that the two debug 512settings in question can be tuned arbitrarily. 513.Pp 514To destroy that same subtree: 515.Bd -literal -offset indent -compact 516sysctl -w //destroy=local.esm_debug 517sysctl -w //destroy=local.audiodebug 518sysctl -w //destroy=local 519.Ed 520.Sh SEE ALSO 521.Xr sysctl 3 , 522.Xr ksyms 4 , 523.Xr sysctl 7 524.Sh HISTORY 525.Nm sysctl 526first appeared in 527.Bx 4.4 . 528