| blob | a16aa4f0479fb21d9fc5b3fcb7ba102be189eaa1 |
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
95 The
96 .Nm sysctl
97 utility retrieves kernel state and allows processes with
98 appropriate privilege to set kernel state.
99 The state to be retrieved or set is described using a
100 ``Management Information Base'' (``MIB'') style name,
101 described as a dotted set of components.
102 The
103 .Sq /
104 character may also be used as a separator and a leading separator
105 character is accepted.
106 If
107 .Ar name
108 specifies a non-leaf node in the MIB, all the nodes underneath
109 .Ar name
110 will be printed.
111 .Pp
112 The following options are available:
113 .Bl -tag -width indent
114 .It Fl A
115 List all the known MIB names including tables, unless any MIB
116 arguments or
117 .Fl f Ar file
118 are given.
119 Those with string or integer values will be printed as with the
120 .Fl a
121 flag; for table or structure values that
122 .Nm
123 is not able to print,
124 the name of the utility to retrieve them is given.
125 Errors in retrieving or setting values will be directed to stdout
126 instead of stderr.
127 .It Fl a
128 List all the currently available string or integer values.
129 The use of a solitary separator character (either
130 .Sq \&.
131 or
132 .Sq / )
133 by
134 itself has the same effect.
135 Any given
136 .Ar name
137 arguments are ignored if this option is specified.
138 .It Fl d
139 Descriptions of each of the nodes selected will be printed instead of
140 their values.
141 .It Fl e
142 Separate the name and the value of the variable(s) with
143 .Ql = .
144 This is useful for producing output which can be fed back to the
145 .Nm
146 utility.
147 This option is ignored if
148 .Fl n
149 is specified or a variable is being set.
150 .It Fl f
151 Specifies the name of a file to read and process.
152 Blank lines and comments (beginning with
153 .Ql # )
154 are ignored.
155 Line continuations with
156 .Ql \e
157 are permitted.
158 Remaining lines are processed similarly to
159 command line arguments of the form
160 .Ar name
161 or
162 .Ar name Ns Li = Ns Ar value .
163 The
164 .Fl w
165 flag is implied by
166 .Fl f .
167 Any
168 .Ar name
169 arguments are ignored.
170 .It Fl M
171 Makes
172 .Nm
173 print the MIB instead of any of the actual values contained in the
174 MIB.
175 This causes the entire MIB to be printed unless specific MIB arguments
176 or
177 .Fl f Ar file
178 are also given.
179 .It Fl n
180 Specifies that the printing of the field name should be
181 suppressed and that only its value should be output.
182 This flag is useful for setting shell variables.
183 For example, to save the pagesize in variable psize, use:
184 .Bd -literal -offset indent -compact
185 set psize=`sysctl -n hw.pagesize`
186 .Ed
187 .It Fl q
188 Used to indicate that nothing should be printed for reads or writes unless an
189 error is detected.
190 For reads, not finding a variable does not print an error, but exits with
191 an error code.
192 This is useful just for testing that a variable exists.
193 .It Fl r
194 Raw output form.
195 Values printed are in their raw binary forms as retrieved directly
196 from the kernel.
197 Some additional nodes that
198 .Nm
199 cannot print directly can be retrieved with this flag.
200 This option conflicts with the
201 .Fl x
202 option.
203 .It Fl w
204 Sets the MIB style name given to the value given.
205 The MIB style name and value must be separated by
206 .Ql =
207 with no whitespace.
208 To prevent an error if the MIB style name does not exist (as would be the
209 case with optional kernel components), one can separate the MIB style name
210 and the value with
211 .Ql ?= .
212 Only integral and string values can be set via this method.
213 .It Fl x
214 Makes
215 .Nm
216 print the requested value in a hexadecimal representation instead of
217 its regular form.
218 If specified more than once, the output for each value resembles that of
219 .Xr hexdump 1
220 when given the
221 .Fl C
222 flag.
223 This option conflicts with the
224 .Fl r
225 option.
226 .Pp
227 .El
228 The
229 .Ql proc
230 top-level MIB has a special semantic: it represent per-process values
231 and as such may differ from one process to another.
232 The second-level name is the pid of the process (in decimal form),
233 or the special word
234 .Ql curproc .
235 For variables below
236 .Ql proc. Ns Ao pid Ac Ns .rlimit ,
237 the integer value may be replaced
238 with the string
239 .Ql unlimited
240 if it matches the magic value used to disable
241 a limit.
242 .Pp
243 The information available from
244 .Nm sysctl
245 consists of integers, strings, and tables.
246 The tabular information can only be retrieved by special
247 purpose programs such as
248 .Nm ps ,
249 .Nm systat ,
250 and
251 .Nm netstat .
252 See
253 .Xr sysctl 7
254 for description of available MIBs.
255 .Sh CREATION AND DELETION
256 New nodes are allowed to be created by the superuser when the kernel
257 is running at security level 0.
258 These new nodes may refer to existing kernel data or to new data that
259 is only instrumented by
260 .Xr sysctl 3
261 itself.
262 .Pp
263 The syntax for creating new nodes is
264 .Dq //create=new.node.path
265 followed by one or more of the following attributes separated by
266 commas.
267 The use of a double separator (both
268 .Sq /
269 and
270 .Sq \&.
271 can be used as
272 separators) as the prefix tells sysctl that the first series of tokens
273 is not a MIB name, but a command.
274 It is recommended that the double separator preceding the command not
275 be the same as the separator used in naming the MIB entry so as to
276 avoid possible parse conflicts.
277 The
278 .Dq value
279 assigned, if one is given, must be last.
280 .Pp
281 .Bl -bullet -compact
282 .It
283 .Ar type= Ns Aq Ar T
284 where
285 .Ar T
286 must be one of
287 .Dq node ,
288 .Dq int ,
289 .Dq string ,
290 .Dq quad ,
291 or
292 .Dq struct .
293 If the type is omitted, the
294 .Dq node
295 type is assumed.
296 .It
297 .Ar size= Ns Aq Ar S
298 here,
299 .Ar S
300 asserts the size of the new node.
301 Nodes of type
302 .Dq node
303 should not have a size set.
304 The size may be omitted for nodes of types
305 .Dq int
306 or
307 .Dq quad .
308 If the size is omitted for a node of type
309 .Dq string ,
310 the size will be determined by the length of the given value, or by
311 the kernel for kernel strings.
312 Nodes of type
313 .Dq struct
314 must have their size explicitly set.
315 .It
316 .Ar addr= Ns Aq Ar A
317 or
318 .Ar symbol= Ns Aq Ar A
319 The kernel address of the data being instrumented.
320 If
321 .Dq symbol
322 is used, the symbol must be globally visible to the in-kernel
323 .Xr ksyms 4
324 driver.
325 .It
326 .Ar n= Ns Aq Ar N
327 The MIB number to be assigned to the new node.
328 If no number is specified, the kernel will assign a value.
329 .It
330 .Ar flags= Ns Aq Ar F
331 A concatenated string of single letters that govern the behavior of
332 the node.
333 Flags currently available are:
334 .Bl -tag -width www
335 .It a
336 Allow anyone to write to the node, if it is writable.
337 .It h
338 .Dq Hidden .
339 .Nm
340 must be invoked with
341 .Fl A
342 or the hidden node must be specifically requested in order to see it
343 .It i
344 .Dq Immediate .
345 Makes the node store data in itself, rather than allocating new space
346 for it.
347 This is the default for nodes of type
348 .Dq int
349 and
350 .Dq quad .
351 This is the opposite of owning data.
352 .It o
353 .Dq Own .
354 When the node is created, separate space will be allocated to store
355 the data to be instrumented.
356 This is the default for nodes of type
357 .Dq string
358 and
359 .Dq struct
360 where it is not possible to guarantee sufficient space to store the
361 data in the node itself.
362 .It p
363 .Dq Private .
364 Nodes that are marked private, and children of nodes so marked, are
365 only viewable by the superuser.
366 Be aware that the immediate data that some nodes may store is not
367 necessarily protected by this.
368 .It x
369 .Dq Hexadecimal .
370 Make
371 .Nm
372 default to hexadecimal display of the retrieved value
373 .It r
374 .Dq Read-only .
375 The data instrumented by the given node is read-only.
376 Note that other mechanisms may still exist for changing the data.
377 This is the default for nodes that instrument data.
378 .It w
379 .Dq Writable .
380 The data instrumented by the given node is writable at any time.
381 This is the default for nodes that can have children.
382 .El
383 .Pp
384 .It
385 .Ar value= Ns Aq Ar V
386 An initial starting value for a new node that does not reference
387 existing kernel data.
388 Initial values can only be assigned for nodes of the
389 .Dq int ,
390 .Dq quad ,
391 and
392 .Dq string
393 types.
394 .El
395 .Pp
396 New nodes must fit the following set of criteria:
397 .Pp
398 .Bl -bullet -compact
399 .It
400 If the new node is to address an existing kernel object, only one of the
401 .Dq symbol
402 or
403 .Dq addr
404 arguments may be given.
405 .It
406 The size for a
407 .Dq struct
408 type node must be specified; no initial value is expected or permitted.
409 .It
410 Either the size or the initial value for a
411 .Dq string
412 node must be given.
413 .It
414 The node which will be the parent of the new node must be writable.
415 .El
416 .Pp
417 If any of the given parameters describes an invalid configuration,
418 .Nm
419 will emit a diagnostic message to the standard error and exit.
420 .Pp
421 Descriptions can be added by the super-user to any node that does not
422 have one, provided that the node is not marked with the
423 .Dq PERMANENT
424 flag.
425 The syntax is similar to the syntax for creating new nodes with the
426 exception of the keyword that follows the double separator at the
427 start of the command:
428 .Dq //describe=new.node.path=new node description .
429 Once a description has been added, it cannot be changed or removed.
430 .Pp
431 When destroying nodes, only the path to the node is necessary, i.e.,
432 .Dq //destroy=old.node.path .
433 No other parameters are expected or permitted.
434 Nodes being destroyed must have no children, and their parent must be
435 writable.
436 Nodes that are marked with the
437 .Dq Dv PERMANENT
438 flag (as assigned by the kernel) may not be deleted.
439 .Pp
440 In all cases, the initial
441 .Sq =
442 that follows the command (eg,
443 .Dq create ,
444 .Dq destroy ,
445 or
446 .Dq describe )
447 may be replaced with another instance of the separator character,
448 provided that the same separator character is used for the length of
449 the name specification.
450 .Sh FILES
451 .Bl -tag -width /etc/sysctl.conf -compact
452 .It Pa /etc/sysctl.conf
453 .Nm
454 variables set at boot time
455 .El
456 .Sh EXAMPLES
457 For example, to retrieve the maximum number of processes allowed
458 in the system, one would use the following request:
459 .Bd -literal -offset indent -compact
460 sysctl kern.maxproc
461 .Ed
462 .Pp
463 To set the maximum number of processes allowed
464 in the system to 1000, one would use the following request:
465 .Bd -literal -offset indent -compact
466 sysctl -w kern.maxproc=1000
467 .Ed
468 .Pp
469 Information about the system clock rate may be obtained with:
470 .Bd -literal -offset indent -compact
471 sysctl kern.clockrate
472 .Ed
473 .Pp
474 Information about the load average history may be obtained with:
475 .Bd -literal -offset indent -compact
476 sysctl vm.loadavg
477 .Ed
478 .Pp
479 To view the values of the per-process variables of the current shell,
480 the request:
481 .Bd -literal -offset indent -compact
482 sysctl proc.$$
483 .Ed
484 can be used if the shell interpreter replaces $$ with its pid (this is true
485 for most shells).
486 .Pp
487 To redirect core dumps to the
488 .Pa /var/tmp/ Ns Aq username
489 directory,
490 .Bd -literal -offset indent -compact
491 sysctl -w proc.$$.corename=/var/tmp/%u/%n.core
492 .Ed
493 should be used.
494 .Bd -literal -offset indent -compact
495 sysctl -w proc.curproc.corename=/var/tmp/%u/%n.core
496 .Ed
497 changes the value for the sysctl process itself, and will not have the desired
498 effect.
499 .Pp
500 To create the root of a new sub-tree called
501 .Dq local
502 add some children to the new node, and some descriptions:
503 .Bd -literal -offset indent -compact
504 sysctl -w //create=local
505 sysctl -w //describe=local=my local sysctl tree
506 sysctl -w //create=local.esm_debug,type=int,symbol=esm_debug,flags=w
507 sysctl -w //describe=local.esm_debug=esm driver debug knob
508 sysctl -w //create=local.audiodebug,type=int,symbol=audiodebug,flags=w
509 sysctl -w //describe=local.audiodebug=generic audio debug knob
510 .Ed
511 Note that the children are made writable so that the two debug
512 settings in question can be tuned arbitrarily.
513 .Pp
514 To destroy that same subtree:
515 .Bd -literal -offset indent -compact
516 sysctl -w //destroy=local.esm_debug
517 sysctl -w //destroy=local.audiodebug
518 sysctl -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
526 first appeared in
527 .Bx 4.4 .