| blob | c5b50412a37938f808fbb20769055ced1e75bc3d |
1 .\" $NetBSD: sysctl.8,v 1.160 2009/04/01 15:55:27 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 September 30, 2009
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 AdeMn
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 writes unless an
189 error is detected.
190 .It Fl r
191 Raw output form.
192 Values printed are in their raw binary forms as retrieved directly
193 from the kernel.
194 Some additional nodes that
195 .Nm
196 cannot print directly can be retrieved with this flag.
197 This option conflicts with the
198 .Fl x
199 option.
200 .It Fl w
201 Sets the MIB style name given to the value given.
202 The MIB style name and value must be separated by
203 .Ql =
204 with no whitespace.
205 To prevent an error if the MIB style name does not exist (as would be the
206 case with optional kernel components), one can separate the MIB style name
207 and the value with
208 .Ql ?= .
209 Only integral and string values can be set via this method.
210 .It Fl x
211 Makes
212 .Nm
213 print the requested value in a hexadecimal representation instead of
214 its regular form.
215 If specified more than once, the output for each value resembles that of
216 .Xr hexdump 1
217 when given the
218 .Fl C
219 flag.
220 This option conflicts with the
221 .Fl r
222 option.
223 .Pp
224 .El
225 The
226 .Ql proc
227 top-level MIB has a special semantic: it represent per-process values
228 and as such may differ from one process to another.
229 The second-level name is the pid of the process (in decimal form),
230 or the special word
231 .Ql curproc .
232 For variables below
233 .Ql proc. Ns Ao pid Ac Ns .rlimit ,
234 the integer value may be replaced
235 with the string
236 .Ql unlimited
237 if it matches the magic value used to disable
238 a limit.
239 .Pp
240 The information available from
241 .Nm sysctl
242 consists of integers, strings, and tables.
243 The tabular information can only be retrieved by special
244 purpose programs such as
245 .Nm ps ,
246 .Nm systat ,
247 and
248 .Nm netstat .
249 See
250 .Xr sysctl 7
251 for description of available MIBs.
252 .Sh CREATION AND DELETION
253 New nodes are allowed to be created by the superuser when the kernel
254 is running at security level 0.
255 These new nodes may refer to existing kernel data or to new data that
256 is only instrumented by
257 .Xr sysctl 3
258 itself.
259 .Pp
260 The syntax for creating new nodes is
261 .Dq //create=new.node.path
262 followed by one or more of the following attributes separated by
263 commas.
264 The use of a double separator (both
265 .Sq /
266 and
267 .Sq \&.
268 can be used as
269 separators) as the prefix tells sysctl that the first series of tokens
270 is not a MIB name, but a command.
271 It is recommended that the double separator preceding the command not
272 be the same as the separator used in naming the MIB entry so as to
273 avoid possible parse conflicts.
274 The
275 .Dq value
276 assigned, if one is given, must be last.
277 .Pp
278 .Bl -bullet -compact
279 .It
280 .Ar type= Ns Aq Ar T
281 where
282 .Ar T
283 must be one of
284 .Dq node ,
285 .Dq int ,
286 .Dq string ,
287 .Dq quad ,
288 or
289 .Dq struct .
290 If the type is omitted, the
291 .Dq node
292 type is assumed.
293 .It
294 .Ar size= Ns Aq Ar S
295 here,
296 .Ar S
297 asserts the size of the new node.
298 Nodes of type
299 .Dq node
300 should not have a size set.
301 The size may be omitted for nodes of types
302 .Dq int
303 or
304 .Dq quad .
305 If the size is omitted for a node of type
306 .Dq string ,
307 the size will be determined by the length of the given value, or by
308 the kernel for kernel strings.
309 Nodes of type
310 .Dq struct
311 must have their size explicitly set.
312 .It
313 .Ar addr= Ns Aq Ar A
314 or
315 .Ar symbol= Ns Aq Ar A
316 The kernel address of the data being instrumented.
317 If
318 .Dq symbol
319 is used, the symbol must be globally visible to the in-kernel
320 .Xr ksyms 4
321 driver.
322 .It
323 .Ar n= Ns Aq Ar N
324 The MIB number to be assigned to the new node.
325 If no number is specified, the kernel will assign a value.
326 .It
327 .Ar flags= Ns Aq Ar F
328 A concatenated string of single letters that govern the behavior of
329 the node.
330 Flags currently available are:
331 .Bl -tag -width www
332 .It a
333 Allow anyone to write to the node, if it is writable.
334 .It h
335 .Dq Hidden .
336 .Nm
337 must be invoked with
338 .Fl A
339 or the hidden node must be specifically requested in order to see it
340 .It i
341 .Dq Immediate .
342 Makes the node store data in itself, rather than allocating new space
343 for it.
344 This is the default for nodes of type
345 .Dq int
346 and
347 .Dq quad .
348 This is the opposite of owning data.
349 .It o
350 .Dq Own .
351 When the node is created, separate space will be allocated to store
352 the data to be instrumented.
353 This is the default for nodes of type
354 .Dq string
355 and
356 .Dq struct
357 where it is not possible to guarantee sufficient space to store the
358 data in the node itself.
359 .It p
360 .Dq Private .
361 Nodes that are marked private, and children of nodes so marked, are
362 only viewable by the superuser.
363 Be aware that the immediate data that some nodes may store is not
364 necessarily protected by this.
365 .It x
366 .Dq Hexadecimal .
367 Make
368 .Nm
369 default to hexadecimal display of the retrieved value
370 .It r
371 .Dq Read-only .
372 The data instrumented by the given node is read-only.
373 Note that other mechanisms may still exist for changing the data.
374 This is the default for nodes that instrument data.
375 .It w
376 .Dq Writable .
377 The data instrumented by the given node is writable at any time.
378 This is the default for nodes that can have children.
379 .El
380 .Pp
381 .It
382 .Ar value= Ns Aq Ar V
383 An initial starting value for a new node that does not reference
384 existing kernel data.
385 Initial values can only be assigned for nodes of the
386 .Dq int ,
387 .Dq quad ,
388 and
389 .Dq string
390 types.
391 .El
392 .Pp
393 New nodes must fit the following set of criteria:
394 .Pp
395 .Bl -bullet -compact
396 .It
397 If the new node is to address an existing kernel object, only one of the
398 .Dq symbol
399 or
400 .Dq addr
401 arguments may be given.
402 .It
403 The size for a
404 .Dq struct
405 type node must be specified; no initial value is expected or permitted.
406 .It
407 Either the size or the initial value for a
408 .Dq string
409 node must be given.
410 .It
411 The node which will be the parent of the new node must be writable.
412 .El
413 .Pp
414 If any of the given parameters describes an invalid configuration,
415 .Nm
416 will emit a diagnostic message to the standard error and exit.
417 .Pp
418 Descriptions can be added by the super-user to any node that does not
419 have one, provided that the node is not marked with the
420 .Dq PERMANENT
421 flag.
422 The syntax is similar to the syntax for creating new nodes with the
423 exception of the keyword that follows the double separator at the
424 start of the command:
425 .Dq //describe=new.node.path=new node description .
426 Once a description has been added, it cannot be changed or removed.
427 .Pp
428 When destroying nodes, only the path to the node is necessary, i.e.,
429 .Dq //destroy=old.node.path .
430 No other parameters are expected or permitted.
431 Nodes being destroyed must have no children, and their parent must be
432 writable.
433 Nodes that are marked with the
434 .Dq Dv PERMANENT
435 flag (as assigned by the kernel) may not be deleted.
436 .Pp
437 In all cases, the initial
438 .Sq =
439 that follows the command (eg,
440 .Dq create ,
441 .Dq destroy ,
442 or
443 .Dq describe )
444 may be replaced with another instance of the separator character,
445 provided that the same separator character is used for the length of
446 the name specification.
447 .Sh FILES
448 .Bl -tag -width /etc/sysctl.conf -compact
449 .It Pa /etc/sysctl.conf
450 .Nm
451 variables set at boot time
452 .El
453 .Sh EXAMPLES
454 For example, to retrieve the maximum number of processes allowed
455 in the system, one would use the following request:
456 .Bd -literal -offset indent -compact
457 sysctl kern.maxproc
458 .Ed
459 .Pp
460 To set the maximum number of processes allowed
461 in the system to 1000, one would use the following request:
462 .Bd -literal -offset indent -compact
463 sysctl -w kern.maxproc=1000
464 .Ed
465 .Pp
466 Information about the system clock rate may be obtained with:
467 .Bd -literal -offset indent -compact
468 sysctl kern.clockrate
469 .Ed
470 .Pp
471 Information about the load average history may be obtained with:
472 .Bd -literal -offset indent -compact
473 sysctl vm.loadavg
474 .Ed
475 .Pp
476 To view the values of the per-process variables of the current shell,
477 the request:
478 .Bd -literal -offset indent -compact
479 sysctl proc.$$
480 .Ed
481 can be used if the shell interpreter replaces $$ with its pid (this is true
482 for most shells).
483 .Pp
484 To redirect core dumps to the
485 .Pa /var/tmp/ Ns Aq username
486 directory,
487 .Bd -literal -offset indent -compact
488 sysctl -w proc.$$.corename=/var/tmp/%u/%n.core
489 .Ed
490 should be used.
491 .Bd -literal -offset indent -compact
492 sysctl -w proc.curproc.corename=/var/tmp/%u/%n.core
493 .Ed
494 changes the value for the sysctl process itself, and will not have the desired
495 effect.
496 .Pp
497 To create the root of a new sub-tree called
498 .Dq local
499 add some children to the new node, and some descriptions:
500 .Bd -literal -offset indent -compact
501 sysctl -w //create=local
502 sysctl -w //describe=local=my local sysctl tree
503 sysctl -w //create=local.esm_debug,type=int,symbol=esm_debug,flags=w
504 sysctl -w //describe=local.esm_debug=esm driver debug knob
505 sysctl -w //create=local.audiodebug,type=int,symbol=audiodebug,flags=w
506 sysctl -w //describe=local.audiodebug=generic audio debug knob
507 .Ed
508 Note that the children are made writable so that the two debug
509 settings in question can be tuned arbitrarily.
510 .Pp
511 To destroy that same subtree:
512 .Bd -literal -offset indent -compact
513 sysctl -w //destroy=local.esm_debug
514 sysctl -w //destroy=local.audiodebug
515 sysctl -w //destroy=local
516 .Ed
517 .Sh SEE ALSO
518 .Xr sysctl 3 ,
519 .Xr ksyms 4 ,
520 .Xr sysctl 7
521 .Sh HISTORY
522 .Nm sysctl
523 first appeared in
524 .Bx 4.4 .