xref: /freebsd/sbin/sysctl/sysctl.8 (revision 7e265faeb98d570da9ad66f015d18c3d1210786e)
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.\" 4. 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 January 17, 2011
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 bdehiNnoqx
40.Ar name Ns Op = Ns Ar value
41.Ar ...
42.Nm
43.Op Fl bdehNnoqx
44.Fl a
45.Sh DESCRIPTION
46The
47.Nm
48utility retrieves kernel state and allows processes with appropriate
49privilege to set kernel state.
50The state to be retrieved or set is described using a
51.Dq Management Information Base
52.Pq Dq MIB
53style name, described as a dotted set of
54components.
55.Pp
56The following options are available:
57.Bl -tag -width indent
58.It Fl A
59Equivalent to
60.Fl o a
61(for compatibility).
62.It Fl a
63List all the currently available non-opaque values.
64This option is ignored if one or more variable names are specified on
65the command line.
66.It Fl b
67Force the value of the variable(s) to be output in raw, binary format.
68No names are printed and no terminating newlines are output.
69This is mostly useful with a single variable.
70.It Fl d
71Print the description of the variable instead of its value.
72.It Fl e
73Separate the name and the value of the variable(s) with
74.Ql = .
75This is useful for producing output which can be fed back to the
76.Nm
77utility.
78This option is ignored if either
79.Fl N
80or
81.Fl n
82is specified, or a variable is being set.
83.It Fl h
84Format output for human, rather than machine, readability.
85.It Fl i
86Ignore unknown OIDs.
87The purpose is to make use of
88.Nm
89for collecting data from a variety of machines (not all of which
90are necessarily running exactly the same software) easier.
91.It Fl N
92Show only variable names, not their values.
93This is particularly useful with shells that offer programmable
94completion.
95To enable completion of variable names in
96.Xr zsh 1 Pq Pa ports/shells/zsh ,
97use the following code:
98.Bd -literal -offset indent
99listsysctls () { set -A reply $(sysctl -AN ${1%.*}) }
100compctl -K listsysctls sysctl
101.Ed
102.Pp
103To enable completion of variable names in
104.Xr tcsh 1 ,
105use:
106.Pp
107.Dl "complete sysctl 'n/*/`sysctl -Na`/'"
108.It Fl n
109Show only variable values, not their names.
110This option is useful for setting shell variables.
111For instance, to save the pagesize in variable
112.Va psize ,
113use:
114.Pp
115.Dl "set psize=`sysctl -n hw.pagesize`"
116.It Fl o
117Show opaque variables (which are normally suppressed).
118The format and length are printed, as well as a hex dump of the first
119sixteen bytes of the value.
120.It Fl q
121Suppress some warnings generated by
122.Nm
123to standard error.
124.It Fl X
125Equivalent to
126.Fl x a
127(for compatibility).
128.It Fl x
129As
130.Fl o ,
131but prints a hex dump of the entire value instead of just the first
132few bytes.
133.El
134.Pp
135The information available from
136.Nm
137consists of integers, strings, and opaque types.
138The
139.Nm
140utility
141only knows about a couple of opaque types, and will resort to hexdumps
142for the rest.
143The opaque information is much more useful if retrieved by special
144purpose programs such as
145.Xr ps 1 ,
146.Xr systat 1 ,
147and
148.Xr netstat 1 .
149.Pp
150Some of the variables which cannot be modified during normal system
151operation can be initialized via
152.Xr loader 8
153tunables.
154This can for example be done by setting them in
155.Xr loader.conf 5 .
156Please refer to
157.Xr loader.conf 5
158for more information on which tunables are available and how to set them.
159.Pp
160The string and integer information is summarized below.
161For a detailed description of these variable see
162.Xr sysctl 3 .
163.Pp
164The changeable column indicates whether a process with appropriate
165privilege can change the value.
166String and integer values can be set using
167.Nm .
168.Bl -column security.bsd.unprivileged_read_msgbuf integerxxx
169.It Sy "Name	Type	Changeable
170.It "kern.ostype	string	no
171.It "kern.osrelease	string	no
172.It "kern.osrevision	integer	no
173.It "kern.version	string	no
174.It "kern.maxvnodes	integer	yes
175.It "kern.maxproc	integer	no
176.It "kern.maxprocperuid	integer	yes
177.It "kern.maxfiles	integer	yes
178.It "kern.maxfilesperproc	integer	yes
179.It "kern.argmax	integer	no
180.It "kern.securelevel	integer	raise only
181.It "kern.hostname	string	yes
182.It "kern.hostid	integer	yes
183.It "kern.clockrate	struct	no
184.It "kern.posix1version	integer	no
185.It "kern.ngroups	integer	no
186.It "kern.job_control	integer	no
187.It "kern.saved_ids	integer	no
188.It "kern.boottime	struct	no
189.It "kern.domainname	string	yes
190.It "kern.filedelay	integer	yes
191.It "kern.dirdelay	integer	yes
192.It "kern.metadelay	integer	yes
193.It "kern.osreldate	string	no
194.It "kern.bootfile	string	yes
195.It "kern.corefile	string	yes
196.It "kern.logsigexit	integer	yes
197.It "security.bsd.suser_enabled	integer	yes
198.It "security.bsd.see_other_uids	integer	yes
199.It "security.bsd.unprivileged_proc_debug	integer	yes
200.It "security.bsd.unprivileged_read_msgbuf	integer	yes
201.It "vm.loadavg	struct	no
202.It "hw.machine	string	no
203.It "hw.model	string	no
204.It "hw.ncpu	integer	no
205.It "hw.byteorder	integer	no
206.It "hw.physmem	integer	no
207.It "hw.usermem	integer	no
208.It "hw.pagesize	integer	no
209.It "hw.floatingpoint	integer	no
210.It "hw.machine_arch	string	no
211.It "hw.realmem	integer	no
212.It "machdep.adjkerntz	integer	yes
213.It "machdep.disable_rtc_set	integer	yes
214.It "machdep.guessed_bootdev	string	no
215.It "user.cs_path	string	no
216.It "user.bc_base_max	integer	no
217.It "user.bc_dim_max	integer	no
218.It "user.bc_scale_max	integer	no
219.It "user.bc_string_max	integer	no
220.It "user.coll_weights_max	integer	no
221.It "user.expr_nest_max	integer	no
222.It "user.line_max	integer	no
223.It "user.re_dup_max	integer	no
224.It "user.posix2_version	integer	no
225.It "user.posix2_c_bind	integer	no
226.It "user.posix2_c_dev	integer	no
227.It "user.posix2_char_term	integer	no
228.It "user.posix2_fort_dev	integer	no
229.It "user.posix2_fort_run	integer	no
230.It "user.posix2_localedef	integer	no
231.It "user.posix2_sw_dev	integer	no
232.It "user.posix2_upe	integer	no
233.It "user.stream_max	integer	no
234.It "user.tzname_max	integer	no
235.El
236.Sh FILES
237.Bl -tag -width ".In netinet/icmp_var.h" -compact
238.It In sys/sysctl.h
239definitions for top level identifiers, second level kernel and hardware
240identifiers, and user level identifiers
241.It In sys/socket.h
242definitions for second level network identifiers
243.It In sys/gmon.h
244definitions for third level profiling identifiers
245.It In vm/vm_param.h
246definitions for second level virtual memory identifiers
247.It In netinet/in.h
248definitions for third level Internet identifiers and
249fourth level IP identifiers
250.It In netinet/icmp_var.h
251definitions for fourth level ICMP identifiers
252.It In netinet/udp_var.h
253definitions for fourth level UDP identifiers
254.El
255.Sh EXAMPLES
256For example, to retrieve the maximum number of processes allowed
257in the system, one would use the following request:
258.Pp
259.Dl "sysctl kern.maxproc"
260.Pp
261To set the maximum number of processes allowed
262per uid to 1000, one would use the following request:
263.Pp
264.Dl "sysctl kern.maxprocperuid=1000"
265.Pp
266Information about the system clock rate may be obtained with:
267.Pp
268.Dl "sysctl kern.clockrate"
269.Pp
270Information about the load average history may be obtained with:
271.Pp
272.Dl "sysctl vm.loadavg"
273.Pp
274More variables than these exist, and the best and likely only place
275to search for their deeper meaning is undoubtedly the source where
276they are defined.
277.Sh COMPATIBILITY
278The
279.Fl w
280option has been deprecated and is silently ignored.
281.Sh SEE ALSO
282.Xr sysctl 3 ,
283.Xr loader.conf 5 ,
284.Xr sysctl.conf 5 ,
285.Xr loader 8
286.Sh HISTORY
287A
288.Nm
289utility first appeared in
290.Bx 4.4 .
291.Pp
292In
293.Fx 2.2 ,
294.Nm
295was significantly remodeled.
296.Sh BUGS
297The
298.Nm
299utility presently exploits an undocumented interface to the kernel
300sysctl facility to traverse the sysctl tree and to retrieve format
301and name information.
302This correct interface is being thought about for the time being.
303