xref: /freebsd/sbin/sysctl/sysctl.8 (revision ab00ac327a66a53edaac95b536b209db3ae2cd9f)
1.\" Copyright (c) 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"	From: @(#)sysctl.8	8.1 (Berkeley) 6/6/93
29.\" $FreeBSD$
30.\"
31.Dd December 10, 2015
32.Dt SYSCTL 8
33.Os
34.Sh NAME
35.Nm sysctl
36.Nd get or set kernel state
37.Sh SYNOPSIS
38.Nm
39.Op Fl bdehiNnoRTtqx
40.Op Fl B Ar bufsize
41.Op Fl f Ar filename
42.Ar name Ns Op = Ns Ar value
43.Ar ...
44.Nm
45.Op Fl bdehNnoRTtqx
46.Op Fl B Ar bufsize
47.Fl a
48.Sh DESCRIPTION
49The
50.Nm
51utility retrieves kernel state and allows processes with appropriate
52privilege to set kernel state.
53The state to be retrieved or set is described using a
54.Dq Management Information Base
55.Pq Dq MIB
56style name, described as a dotted set of
57components.
58.Pp
59The following options are available:
60.Bl -tag -width indent
61.It Fl A
62Equivalent to
63.Fl o a
64(for compatibility).
65.It Fl a
66List all the currently available non-opaque values.
67This option is ignored if one or more variable names are specified on
68the command line.
69.It Fl b
70Force the value of the variable(s) to be output in raw, binary format.
71No names are printed and no terminating newlines are output.
72This is mostly useful with a single variable.
73.It Fl B Ar bufsize
74Set the buffer size to read from the
75.Nm
76to
77.Ar bufsize .
78This is necessary for a
79.Nm
80that has variable length, and the probe value of 0 is a valid length, such as
81.Va kern.arandom .
82.It Fl d
83Print the description of the variable instead of its value.
84.It Fl e
85Separate the name and the value of the variable(s) with
86.Ql = .
87This is useful for producing output which can be fed back to the
88.Nm
89utility.
90This option is ignored if either
91.Fl N
92or
93.Fl n
94is specified, or a variable is being set.
95.It Fl f Ar filename
96Specify a file which contains a pair of name and value in each line.
97.Nm
98reads and processes the specified file first and then processes the name
99and value pairs in the command line argument.
100.It Fl h
101Format output for human, rather than machine, readability.
102.It Fl i
103Ignore unknown OIDs.
104The purpose is to make use of
105.Nm
106for collecting data from a variety of machines (not all of which
107are necessarily running exactly the same software) easier.
108.It Fl N
109Show only variable names, not their values.
110This is particularly useful with shells that offer programmable
111completion.
112To enable completion of variable names in
113.Xr zsh 1 Pq Pa ports/shells/zsh ,
114use the following code:
115.Bd -literal -offset indent
116listsysctls () { set -A reply $(sysctl -AN ${1%.*}) }
117compctl -K listsysctls sysctl
118.Ed
119.Pp
120To enable completion of variable names in
121.Xr tcsh 1 ,
122use:
123.Pp
124.Dl "complete sysctl 'n/*/`sysctl -Na`/'"
125.It Fl n
126Show only variable values, not their names.
127This option is useful for setting shell variables.
128For instance, to save the pagesize in variable
129.Va psize ,
130use:
131.Pp
132.Dl "set psize=`sysctl -n hw.pagesize`"
133.It Fl o
134Show opaque variables (which are normally suppressed).
135The format and length are printed, as well as a hex dump of the first
136sixteen bytes of the value.
137.It Fl q
138Suppress some warnings generated by
139.Nm
140to standard error.
141.It Fl T
142Display only variables that are settable via loader (CTLFLAG_TUN).
143.It Fl t
144Print the type of the variable.
145.It Fl W
146Display only writable variables that are not statistical.
147Useful for determining the set of runtime tunable sysctls.
148.It Fl X
149Equivalent to
150.Fl x a
151(for compatibility).
152.It Fl x
153As
154.Fl o ,
155but prints a hex dump of the entire value instead of just the first
156few bytes.
157.El
158.Pp
159The information available from
160.Nm
161consists of integers, strings, and opaque types.
162The
163.Nm
164utility
165only knows about a couple of opaque types, and will resort to hexdumps
166for the rest.
167The opaque information is much more useful if retrieved by special
168purpose programs such as
169.Xr ps 1 ,
170.Xr systat 1 ,
171and
172.Xr netstat 1 .
173.Pp
174Some of the variables which cannot be modified during normal system
175operation can be initialized via
176.Xr loader 8
177tunables.
178This can for example be done by setting them in
179.Xr loader.conf 5 .
180Please refer to
181.Xr loader.conf 5
182for more information on which tunables are available and how to set them.
183.Pp
184The string and integer information is summarized below.
185For a detailed description of these variable see
186.Xr sysctl 3 .
187.Pp
188The changeable column indicates whether a process with appropriate
189privilege can change the value.
190String and integer values can be set using
191.Nm .
192.Bl -column security.bsd.unprivileged_read_msgbuf integerxxx
193.It Sy "Name	Type	Changeable"
194.It "kern.ostype	string	no"
195.It "kern.osrelease	string	no"
196.It "kern.osrevision	integer	no"
197.It "kern.version	string	no"
198.It "kern.maxvnodes	integer	yes"
199.It "kern.maxproc	integer	no"
200.It "kern.maxprocperuid	integer	yes"
201.It "kern.maxfiles	integer	yes"
202.It "kern.maxfilesperproc	integer	yes"
203.It "kern.argmax	integer	no"
204.It "kern.securelevel	integer	raise only"
205.It "kern.hostname	string	yes"
206.It "kern.hostid	integer	yes"
207.It "kern.clockrate	struct	no"
208.It "kern.posix1version	integer	no"
209.It "kern.ngroups	integer	no"
210.It "kern.job_control	integer	no"
211.It "kern.saved_ids	integer	no"
212.It "kern.boottime	struct	no"
213.It "kern.domainname	string	yes"
214.It "kern.filedelay	integer	yes"
215.It "kern.dirdelay	integer	yes"
216.It "kern.metadelay	integer	yes"
217.It "kern.osreldate	string	no"
218.It "kern.bootfile	string	yes"
219.It "kern.corefile	string	yes"
220.It "kern.logsigexit	integer	yes"
221.It "security.bsd.suser_enabled	integer	yes"
222.It "security.bsd.see_other_uids	integer	yes"
223.It "security.bsd.unprivileged_proc_debug	integer	yes"
224.It "security.bsd.unprivileged_read_msgbuf	integer	yes"
225.It "vm.loadavg	struct	no"
226.It "hw.machine	string	no"
227.It "hw.model	string	no"
228.It "hw.ncpu	integer	no"
229.It "hw.byteorder	integer	no"
230.It "hw.physmem	integer	no"
231.It "hw.usermem	integer	no"
232.It "hw.pagesize	integer	no"
233.It "hw.floatingpoint	integer	no"
234.It "hw.machine_arch	string	no"
235.It "hw.realmem	integer	no"
236.It "machdep.adjkerntz	integer	yes"
237.It "machdep.disable_rtc_set	integer	yes"
238.It "machdep.guessed_bootdev	string	no"
239.It "user.cs_path	string	no"
240.It "user.bc_base_max	integer	no"
241.It "user.bc_dim_max	integer	no"
242.It "user.bc_scale_max	integer	no"
243.It "user.bc_string_max	integer	no"
244.It "user.coll_weights_max	integer	no"
245.It "user.expr_nest_max	integer	no"
246.It "user.line_max	integer	no"
247.It "user.re_dup_max	integer	no"
248.It "user.posix2_version	integer	no"
249.It "user.posix2_c_bind	integer	no"
250.It "user.posix2_c_dev	integer	no"
251.It "user.posix2_char_term	integer	no"
252.It "user.posix2_fort_dev	integer	no"
253.It "user.posix2_fort_run	integer	no"
254.It "user.posix2_localedef	integer	no"
255.It "user.posix2_sw_dev	integer	no"
256.It "user.posix2_upe	integer	no"
257.It "user.stream_max	integer	no"
258.It "user.tzname_max	integer	no"
259.El
260.Sh FILES
261.Bl -tag -width ".In netinet/icmp_var.h" -compact
262.It In sys/sysctl.h
263definitions for top level identifiers, second level kernel and hardware
264identifiers, and user level identifiers
265.It In sys/socket.h
266definitions for second level network identifiers
267.It In sys/gmon.h
268definitions for third level profiling identifiers
269.It In vm/vm_param.h
270definitions for second level virtual memory identifiers
271.It In netinet/in.h
272definitions for third level Internet identifiers and
273fourth level IP identifiers
274.It In netinet/icmp_var.h
275definitions for fourth level ICMP identifiers
276.It In netinet/udp_var.h
277definitions for fourth level UDP identifiers
278.El
279.Sh EXAMPLES
280For example, to retrieve the maximum number of processes allowed
281in the system, one would use the following request:
282.Pp
283.Dl "sysctl kern.maxproc"
284.Pp
285To set the maximum number of processes allowed
286per uid to 1000, one would use the following request:
287.Pp
288.Dl "sysctl kern.maxprocperuid=1000"
289.Pp
290Information about the system clock rate may be obtained with:
291.Pp
292.Dl "sysctl kern.clockrate"
293.Pp
294Information about the load average history may be obtained with:
295.Pp
296.Dl "sysctl vm.loadavg"
297.Pp
298More variables than these exist, and the best and likely only place
299to search for their deeper meaning is undoubtedly the source where
300they are defined.
301.Sh COMPATIBILITY
302The
303.Fl w
304option has been deprecated and is silently ignored.
305.Sh SEE ALSO
306.Xr sysctl 3 ,
307.Xr loader.conf 5 ,
308.Xr sysctl.conf 5 ,
309.Xr loader 8
310.Sh HISTORY
311A
312.Nm
313utility first appeared in
314.Bx 4.4 .
315.Pp
316In
317.Fx 2.2 ,
318.Nm
319was significantly remodeled.
320.Sh BUGS
321The
322.Nm
323utility presently exploits an undocumented interface to the kernel
324sysctl facility to traverse the sysctl tree and to retrieve format
325and name information.
326This correct interface is being thought about for the time being.
327