NetBSD/sbin/sysctl/sysctl.8

.\"	$NetBSD: sysctl.8,v 1.114 2004/08/27 04:58:10 itojun Exp $
.\"
.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)sysctl.8	8.1 (Berkeley) 6/6/93
.\"
.Dd April 28, 2004
.Dt SYSCTL 8
.Os
.Sh NAME
.Nm sysctl
.Nd get or set kernel state
.Sh SYNOPSIS
.Nm sysctl
.Op Fl AdeMn
.Oo
.Fl r |
.Fl x
.Oc
.Op Ar name ...
.Nm sysctl
.Op Fl nq
.Oo
.Fl r |
.Fl x
.Oc
.Fl w
.Ar name Ns Li = Ns Ar value ...
.Nm sysctl
.Op Fl en
.Oo
.Fl r |
.Fl x
.Oc
.Fl a
.Nm sysctl
.Op Fl nq
.Oo
.Fl r |
.Fl x
.Oc
.Fl f
.Ar file
.Sh DESCRIPTION
The
.Nm sysctl
utility retrieves kernel state and allows processes with
appropriate privilege to set kernel state.
The state to be retrieved or set is described using a
``Management Information Base'' (``MIB'') style name,
described as a dotted set of components.
The
.Sq /
character may also be used as a separator and a leading separator
character is accepted.
If
.Ar name
specifies a non-leaf node in the MIB, all the nodes underneath
.Ar name
will be printed.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl A
List all the known MIB names including tables, unless any MIB
arguments or
.Fl f Ar file
are given.
Those with string or integer values will be printed as with the
.Fl a
flag; for table or structure values that
.Nm
is not able to print,
the name of the utility to retrieve them is given.
Errors in retrieving or setting values will be directed to stdout
instead of stderr.
.It Fl a
List all the currently available string or integer values.
The use of a solitary separator character (either
.Sq \&.
or
.Sq / )
by
itself has the same effect.
Any given
.Ar name
arguments are ignored if this option is specified.
.It Fl d
Descriptions of each of the nodes selected will be printed instead of
their values.
.It Fl e
Separate the name and the value of the variable(s) with
.Ql = .
This is useful for producing output which can be fed back to the
.Nm
utility.
This option is ignored if
.Fl n
is specified or a variable is being set.
.It Fl f
Specifies the name of a file to read and process.
Blank lines and comments (beginning with
.Ql # )
are ignored.
Line continuations with
.Ql \e
are permitted.
Remaining lines are processed similarly to
command line arguments of the form
.Ar name
or
.Ar name Ns Li = Ns Ar value .
The
.Fl w
flag is implied by
.Fl f .
Any
.Ar name
arguments are ignored.
.It Fl M
Makes
.Nm
print the MIB instead of any of the actual values contained in the
MIB.
This causes the entire MIB to be printed unless specific MIB arguments
or
.Fl f Ar file
are also given.
.It Fl n
Specifies that the printing of the field name should be
suppressed and that only its value should be output.
This flag is useful for setting shell variables.
For example, to save the pagesize in variable psize, use:
.Bd -literal -offset indent -compact
set psize=`sysctl -n hw.pagesize`
.Ed
.It Fl q
Used to indicate that nothing should be printed for writes unless an
error is detected.
.It Fl r
Raw output form.
Values printed are in their raw binary forms as retrieved directly
from the kernel.
Some additional nodes that
.Nm
cannot print directly can be retrieved with this flag.
This option conflicts with the
.Fl x
option.
.It Fl w
Sets the MIB style name given to the value given.
The MIB style name and value must be separated by
.Ql =
with no whitespace.
Only integral and string values can be set via this method.
.It Fl x
Makes
.Nm
print the requested value in a hexadecimal representation instead of
its regular form.
If specified more than once, the output for each value resembles that of
.Xr hexdump 1
when given the
.Fl C
flag.
This option conflicts with the
.Fl r
option.
.Pp
.El
The
.Ql proc
top-level MIB has a special semantic: it represent per-process values
and as such may differ from one process to another.
The second-level name is the pid of the process (in decimal form),
or the special word
.Ql curproc .
For variables below
.Ql proc. Ns Ao pid Ac Ns .rlimit ,
the integer value may be replaced
with the string
.Ql unlimited
if it matches the magic value used to disable
a limit.
.Pp
The information available from
.Nm sysctl
consists of integers, strings, and tables.
The tabular information can only be retrieved by special
purpose programs such as
.Nm ps ,
.Nm systat ,
and
.Nm netstat .
The string and integer information is summarized below.
For a detailed description of these variable see
.Xr sysctl 3 .
The changeable column indicates whether a process with appropriate
privilege can change the value.
.Bl -column proc.xpidx.rlimit.coredumpsize.hardxxxxxx integerxxx
.It Sy Name	Type	Changeable
.It ddb.fromconsole	integer 	yes
.It ddb.lines	integer	yes
.It ddb.maxoff	integer	yes
.It ddb.maxwidth	integer	yes
.It ddb.onpanic	integer	yes
.It ddb.radix	integer	yes
.It ddb.tabstops	integer	yes
.It hw.alignbytes	integer	no
.It hw.byteorder	integer	no
.It hw.disknames	string	no
.It hw.diskstats	struct	no
.It hw.machine	string	no
.It hw.machine_arch	string	no
.It hw.model	string	no
.It hw.ncpu	integer	no
.It hw.pagesize	integer	no
.It hw.physmem	integer	no
.It hw.physmem64	quad	no
.It hw.usermem	integer	no
.It hw.usermem64	quad	no
.It hw.cnmagic	string	yes
.It kern.argmax	integer	no
.It kern.autonicetime	integer	yes
.It kern.autoniceval	integer	yes
.It kern.boottime	struct	no
.It kern.ccpu	integer	no
.It kern.chown_restricted	integer	no
.It kern.clockrate	struct	no
.It kern.consdev	integer	no
.It kern.cp_time	struct	no
.It kern.defcorename	string	yes
.It kern.domainname	string	yes
.It kern.drivers	struct	no
.It kern.forkfsleep	integer	yes
.It kern.fscale	integer	no
.It kern.fsync	integer	no
.It kern.hostid	integer	yes
.It kern.hostname	string	yes
.It kern.iov_max	integer	no
.It kern.job_control	integer	no
.It kern.labeloffset	integer	no
.It kern.labelsector	integer	no
.It kern.link_max	integer	no
.It kern.login_name_max	integer	no
.It kern.logsigexit	integer	yes
.It kern.max_canon	integer	no
.It kern.max_input	integer	no
.It kern.maxfiles	integer	yes
.It kern.maxpartitions	integer	no
.It kern.maxproc	integer	yes
.It kern.maxptys	integer	yes, special
.It kern.maxvnodes	integer	raise only
.It kern.mapped_files	integer	no
.It kern.maxphys	integer	no
.It kern.memlock	integer	no
.It kern.memlock_range	integer	no
.It kern.memory_protection	integer	no
.It kern.mbuf.mblowat	integer	yes
.It kern.mbuf.mcllowat	integer	yes
.It kern.mbuf.mclsize	integer	no
.It kern.mbuf.msize	integer	no
.It kern.mbuf.nmbclusters	integer	raise only
.It kern.monotonic_clock	integer	no
.It kern.msgbuf	struct	no
.It kern.msgbufsize	integer	no
.It kern.name_max	integer	no
.It kern.ngroups	integer	no
.It kern.no_trunc	integer	no
.It kern.ntptime	struct	no
.It kern.osrelease	string	no
.It kern.osrevision	integer	no
.It kern.ostype	string	no
.It kern.path_max	integer	no
.It kern.pipe.maxkvasz	integer	yes
.It kern.pipe.maxloankvasz	integer	yes
.It kern.pipe.maxbigpipes	integer	yes
.It kern.pipe.nbigpipes	integer	no
.It kern.pipe.kvasize	integer	no
.It kern.posix1version	integer	no
.It kern.posix_barriers	integer	no
.It kern.posix_reader_writer_locks	integer	no
.It kern.posix_semaphores	integer	no
.It kern.posix_spin_locks	integer	no
.It kern.posix_timers	integer	no
.It kern.posix_threads	integer	no
.It kern.proc2	struct	no
.It kern.proc_args	string	yes
.It kern.rawpartition	integer	no
.It kern.root_device	string	no
.It kern.root_partition	integer	no
.It kern.rtc_offset	integer	no
.It kern.saved_ids	integer	no
.It kern.sbmax	integer	yes
.It kern.securelevel	integer	raise only
.It kern.somaxkva	integer	yes
.It kern.synchronized_io	integer	no
.It kern.sysvipc_info	struct	no
.It kern.sysvmsg	integer	no
.It kern.sysvsem	integer	no
.It kern.sysvshm	integer	no
.It kern.timex	struct	no
.It kern.tkstat.nin	quad	no
.It kern.tkstat.nout	quad	no
.It kern.tkstat.cancc	quad	no
.It kern.tkstat.rawcc	quad	no
.It kern.urnd	integer	no
.It kern.vdisable	integer	no
.It kern.version	string	no
.It machdep.console_device	dev_t	no
.It net.bpf.maxbufsize	integer	yes
.It net.inet.arp.prune	integer	yes
.It net.inet.arp.keep	integer	yes
.It net.inet.arp.down	integer	yes
.It net.inet.arp.refresh	integer	yes
.It net.inet.icmp.maskrepl	integer	yes
.It net.inet.icmp.errppslimit	integer	yes
.It net.inet.icmp.rediraccept	integer	yes
.It net.inet.icmp.redirtimeout	integer	yes
.It net.inet.ip.allowsrcrt	integer	yes
.It net.inet.ip.anonportmax	integer	yes
.It net.inet.ip.anonportmin	integer	yes
.It net.inet.ip.checkinterface	integer	yes
.It net.inet.ip.directed-broadcast	integer	yes
.It net.inet.ip.forwarding	integer	yes
.It net.inet.ip.forwsrcrt	integer	yes
.It net.inet.ip.maxfragpacket	integer	yes
.It net.inet.ip.lowportmax	integer	yes
.It net.inet.ip.lowportmin	integer	yes
.It net.inet.ip.mtudisc	integer	yes
.It net.inet.ip.mtudisctimeout	integer	yes
.It net.inet.ip.redirect	integer	yes
.It net.inet.ip.subnetsarelocal	integer	yes
.It net.inet.ip.ttl	integer	yes
.It net.inet.ipsec.ah_cleartos	integer	yes
.It net.inet.ipsec.ah_net_deflev	integer	yes
.It net.inet.ipsec.ah_offsetmask	integer	yes
.It net.inet.ipsec.ah_trans_deflev	integer	yes
.It net.inet.ipsec.def_policy	integer	yes
.It net.inet.ipsec.dfbit	integer	yes
.It net.inet.ipsec.ecn	integer	yes
.It net.inet.ipsec.esp_net_deflev	integer	yes
.It net.inet.ipsec.esp_trans_deflev	integer	yes
.It net.inet.ipsec.inbound_call_ike	integer	yes
.It net.inet.tcp.ack_on_push	integer	yes
.It net.inet.tcp.compat_42	integer	yes
.It net.inet.tcp.cwm	integer	yes
.It net.inet.tcp.cwm_burstsize	integer	yes
.It net.inet.tcp.init_win	integer	yes
.It net.inet.tcp.init_win_local	integer	yes
.It net.inet.tcp.keepcnt	integer	yes
.It net.inet.tcp.keepidle	integer	yes
.It net.inet.tcp.keepintvl	integer	yes
.It net.inet.tcp.log_refused	integer	yes
.It net.inet.tcp.mss_ifmtu	integer	yes
.It net.inet.tcp.mssdflt	integer	yes
.It net.inet.tcp.recvspace	integer	yes
.It net.inet.tcp.rfc1323	integer	yes
.It net.inet.tcp.rstppslimit	integer	yes
.It net.inet.tcp.sack	integer	yes
.It net.inet.tcp.sendspace	integer	yes
.It net.inet.tcp.slowhz	integer	no
.It net.inet.tcp.syn_bucket_limit	integer	yes
.It net.inet.tcp.syn_cache_interval	integer	yes
.It net.inet.tcp.syn_cache_limit	integer	yes
.It net.inet.tcp.timestamps	integer	yes
.It net.inet.tcp.win_scale	integer	yes
.It net.inet.tcp.ident	struct	no
.It net.inet.udp.checksum	integer	yes
.It net.inet.udp.recvspace	integer	yes
.It net.inet.udp.sendspace	integer	yes
.It net.inet6.icmp6.errppslimit	integer	yes
.It net.inet6.icmp6.mtudisc_hiwat	integer	yes
.It net.inet6.icmp6.mtudisc_lowat	integer	yes
.It net.inet6.icmp6.nd6_debug	integer	yes
.It net.inet6.icmp6.nd6_delay	integer	yes
.It net.inet6.icmp6.nd6_maxnudhint	integer	yes
.It net.inet6.icmp6.nd6_mmaxtries	integer	yes
.It net.inet6.icmp6.nd6_prune	integer	yes
.It net.inet6.icmp6.nd6_umaxtries	integer	yes
.It net.inet6.icmp6.nd6_useloopback	integer	yes
.It net.inet6.icmp6.nodeinfo	integer	yes
.It net.inet6.icmp6.rediraccept	integer	yes
.It net.inet6.icmp6.redirtimeout	integer	yes
.It net.inet6.ip6.accept_rtadv	integer	yes
.It net.inet6.ip6.anonportmax	integer	yes
.It net.inet6.ip6.anonportmin	integer	yes
.It net.inet6.ip6.auto_flowlabel	integer	yes
.It net.inet6.ip6.v6only	integer	yes
.It net.inet6.ip6.dad_count	integer	yes
.It net.inet6.ip6.defmcasthlim	integer	yes
.It net.inet6.ip6.forwarding	integer	yes
.It net.inet6.ip6.gif_hlim	integer	yes
.It net.inet6.ip6.hdrnestlimit	integer	yes
.It net.inet6.ip6.hlim	integer	yes
.It net.inet6.ip6.kame_version	string	no
.It net.inet6.ip6.keepfaith	integer	yes
.It net.inet6.ip6.log_interval	integer	yes
.It net.inet6.ip6.lowportmax	integer	yes
.It net.inet6.ip6.lowportmin	integer	yes
.It net.inet6.ip6.maxfragpackets	integer	yes
.It net.inet6.ip6.maxfrags	integer	yes
.It net.inet6.ip6.redirect	integer	yes
.It net.inet6.ip6.rr_prune	integer	yes
.It net.inet6.ip6.use_deprecated	integer	yes
.It net.inet6.ipsec6.ah_net_deflev	integer	yes
.It net.inet6.ipsec6.ah_trans_deflev	integer	yes
.It net.inet6.ipsec6.def_policy	integer	yes
.It net.inet6.ipsec6.ecn	integer	yes
.It net.inet6.ipsec6.esp_net_deflev	integer	yes
.It net.inet6.ipsec6.esp_trans_deflev	integer	yes
.It net.inet6.ipsec6.inbound_call_ike	integer	yes
.It net.inet6.udp6.recvspace	integer	yes
.It net.inet6.udp6.sendspace	integer	yes
.It net.key.acq_exp_int	integer	yes
.It net.key.acq_maxtime	integer	yes
.It net.key.ah_keymin	integer	yes
.It net.key.debug	integer	yes
.It net.key.esp_auth	integer	yes
.It net.key.esp_keymin	integer	yes
.It net.key.kill_int	integer	yes
.It net.key.spi_max_value	integer	yes
.It net.key.spi_min_value	integer	yes
.It net.key.spi_try	integer	yes
.It proc.\*[Lt]pid\*[Gt].corename	string	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.coredumpsize.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.coredumpsize.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.cputime.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.cputime.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.datasize.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.datasize.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.filesize.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.filesize.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.maxproc.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.maxproc.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.memorylocked.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.memorylocked.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.memoryuse.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.memoryuse.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.stacksize.hard	integer	yes
.It proc.\*[Lt]pid\*[Gt].rlimit.stacksize.soft	integer	yes
.It proc.\*[Lt]pid\*[Gt].stopexec	int	yes
.It proc.\*[Lt]pid\*[Gt].stopfork	int	yes
.It user.bc_base_max	integer	no
.It user.bc_dim_max	integer	no
.It user.bc_scale_max	integer	no
.It user.bc_string_max	integer	no
.It user.coll_weights_max	integer	no
.It user.cs_path	string	no
.It user.expr_nest_max	integer	no
.It user.line_max	integer	no
.It user.posix2_c_bind	integer	no
.It user.posix2_c_dev	integer	no
.It user.posix2_char_term	integer	no
.It user.posix2_fort_dev	integer	no
.It user.posix2_fort_run	integer	no
.It user.posix2_localedef	integer	no
.It user.posix2_sw_dev	integer	no
.It user.posix2_upe	integer	no
.It user.posix2_version	integer	no
.It user.re_dup_max	integer	no
.It vendor.\*[Lt]vendor\*[Gt].*	?	vendor specific
.It vfs.generic.usermount	integer	yes
.It vfs.nfs.iothreads	integer	yes
.It vm.anonmax	integer	yes
.It vm.anonmin	integer	yes
.It vm.execmax	integer	yes
.It vm.execmin	integer	yes
.It vm.filemax	integer	yes
.It vm.filemin	integer	yes
.It vm.loadavg	struct	no
.It vm.nkmempages	integer	no
.It vm.uvmexp	struct	no
.It vm.uvmexp2	struct	no
.It vm.vmmeter	struct	no
.El
.Pp
Entries found under
.Dq vendor. Ns Aq vendor
are left to be specified (and used) by vendors
using the
.Nx
operating system in their products.
Values and structure are vendor-defined, and no registry
exists right now.
.Sh CREATION AND DELETION
New nodes are allowed to be created by the superuser when the kernel
is running at security level 0.
These new nodes may refer to existing kernel data or to new data that
is only instrumented by
.Xr sysctl 3
itself.
.Pp
The syntax for creating new nodes is
.Dq //create=new.node.path
followed by one or more of the following attributes separated by
commas.
The use of a double separator (both
.Sq /
and
.Sq \&.
can be used as
separators) as the prefix tells sysctl that the first series of tokens
is not a MIB name, but a command.
It is recommended that the double separator preceding the command not
be the same as the separator used in naming the MIB entry so as to
avoid possible parse conflicts.
The
.Dq value
assigned, if one is given, must be last.
.Pp
.Bl -bullet -compact
.It
.Ar type= Ns Aq Ar T
where
.Ar T
must be one of
.Dq node ,
.Dq int ,
.Dq string ,
.Dq quad ,
or
.Dq struct .
If the type is omitted, the
.Dq node
type is assumed.
.It
.Ar size= Ns Aq Ar S
here,
.Ar S
asserts the size of the new node.
Nodes of type
.Dq node
should not have a size set.
The size may be omitted for nodes of types
.Dq int
or
.Dq quad .
If the size is omitted for a node of type
.Dq string ,
the size will be determined by the length of the given value, or by
the kernel for kernel strings.
Nodes of type
.Dq struct
must have their size explicitly set.
.It
.Ar addr= Ns Aq Ar A
or
.Ar symbol= Ns Aq Ar A
The kernel address of the data being instrumented.
If
.Dq symbol
is used, the symbol must be globally visible to the in-kernel
.Xr ksyms 4
driver.
.It
.Ar n= Ns Aq Ar N
The MIB number to be assigned to the new node.
If no number is specified, the kernel will assign a value.
.It
.Ar flags= Ns Aq Ar F
A concatenated string of single letters that govern the behavior of
the node.
Flags currently available are:
.Bl -tag -width www
.It a
Allow anyone to write to the node, if it is writable.
.It h
.Dq Hidden .
.Nm
must be invoked with
.Fl A
or the hidden node must be specifically requested in order to see it
.It i
.Dq Immediate .
Makes the node store data in itself, rather than allocating new space
for it.
This is the default for nodes of type
.Dq int
and
.Dq quad .
This is the opposite of owning data.
.It o
.Dq Own .
When the node is created, separate space will be allocated to store
the data to be instrumented.
This is the default for nodes of type
.Dq string
and
.Dq struct
where it is not possible to guarantee sufficient space to store the
data in the node itself.
.It p
.Dq Private .
Nodes that are marked private, and children of nodes so marked, are
only viewable by the superuser.
Be aware that the immediate data that some nodes may store is not
necessarily protected by this.
.It x
.Dq Hexadecimal .
Make
.Nm
default to hexadecimal display of the retrieved value
.It r
.Dq Read-only .
The data instrumented by the given node is read-only.
Note that other mechanisms may still exist for changing the data.
This is the default for nodes that instrument data.
.It w
.Dq Writable .
The data instrumented by the given node is writable at any time.
This is the default for nodes that can have children.
.It 1
.Dq Read-only at securelevel 1 .
The data instrumented by this node is writable until the securelevel
reaches or passes securelevel 1.
Examples of this include some network tunables.
.It 2
.Dq Read-only at securelevel 2 .
The data instrumented by this node is writable until the securelevel
reaches or passes securelevel 2.
An example of this is the per-process core filename setting.
.El
.Pp
.It
.Ar value= Ns Aq Ar V
An initial starting value for a new node that does not reference
existing kernel data.
Initial values can only be assigned for nodes of the
.Dq int ,
.Dq quad ,
and
.Dq string
types.
.El
.Pp
New nodes must fit the following set of criteria:
.Pp
.Bl -bullet -compact
.It
If the new node is to address an existing kernel object, only one of the
.Dq symbol
or
.Dq addr
arguments may be given.
.It
The size for a
.Dq struct
type node must be specified; no initial value is expected or permitted.
.It
Either the size or the initial value for a
.Dq string
node must be given.
.It
The node which will be the parent of the new node must be writable.
.El
.Pp
If any of the given parameters describes an invalid configuration,
.Nm
will emit a diagnostic message to the standard error and exit.
.Pp
Descriptions can be added by the super-user to any node that does not
have one, provided that the node is not marked with the
.Dq PERMANENT
flag.
The syntax is similar to the syntax for creating new nodes with the
exception of the keyword that follows the double separator at the
start of the command:
.Dq //describe=new.node.path=new node description .
Once a description has been added, it cannot be changed or removed.
.Pp
When destroying nodes, only the path to the node is necessary, i.e.,
.Dq //destroy=old.node.path .
No other parameters are expected or permitted.
Nodes being destroyed must have no children, and their parent must be
writable.
Nodes that are marked with the
.Dq Dv PERMANENT
flag (as assigned by the kernel) may not be deleted.
.Pp
In all cases, the initial
.Sq =
that follows the command (eg,
.Dq create ,
.Dq destroy ,
or
.Dq describe )
may be replaced with another instance of the separator character,
provided that the same separator character is used for the length of
the name specification.
.Sh FILES
.Bl -tag -width xnetinet6/udp6Xvar.hx -compact
.It Pa /etc/sysctl.conf
.Nm
variables set at boot time
.It Aq Pa sys/sysctl.h
definitions for top level identifiers, second level kernel and hardware
identifiers, and user level identifiers
.It Aq Pa sys/socket.h
definitions for second level network identifiers
.It Aq Pa sys/gmon.h
definitions for third level profiling identifiers
.It Aq Pa uvm/uvm_param.h
definitions for second level virtual memory identifiers
.It Aq Pa netinet/in.h
definitions for third level IPv4/v6 identifiers and
fourth level IPv4/v6 identifiers
.It Aq Pa netinet/icmp_var.h
definitions for fourth level ICMP identifiers
.It Aq Pa netinet/icmp6.h
definitions for fourth level ICMPv6 identifiers
.It Aq Pa netinet/tcp_var.h
definitions for fourth level TCP identifiers
.It Aq Pa netinet/udp_var.h
definitions for fourth level UDP identifiers
.It Aq Pa netinet6/udp6_var.h
definitions for fourth level IPv6 UDP identifiers
.It Aq Pa netinet6/ipsec.h
definitions for fourth level IPsec identifiers
.It Aq Pa netkey/key_var.h
definitions for third level PF_KEY identifiers
.El
.Sh EXAMPLES
For example, to retrieve the maximum number of processes allowed
in the system, one would use the following request:
.Bd -literal -offset indent -compact
sysctl kern.maxproc
.Ed
.Pp
To set the maximum number of processes allowed
in the system to 1000, one would use the following request:
.Bd -literal -offset indent -compact
sysctl -w kern.maxproc=1000
.Ed
.Pp
Information about the system clock rate may be obtained with:
.Bd -literal -offset indent -compact
sysctl kern.clockrate
.Ed
.Pp
Information about the load average history may be obtained with:
.Bd -literal -offset indent -compact
sysctl vm.loadavg
.Ed
.Pp
To view the values of the per-process variables of the current shell,
the request:
.Bd -literal -offset indent -compact
sysctl proc.$$
.Ed
can be used if the shell interpreter replaces $$ with its pid (this is true
for most shells).
.Pp
To redirect core dumps to the
.Pa /var/tmp/ Ns Aq username
directory,
.Bd -literal -offset indent -compact
sysctl -w proc.$$.corename=/var/tmp/%u/%n.core
.Ed
should be used.
.Bd -literal -offset indent -compact
sysctl -w proc.curproc.corename=/var/tmp/%u/%n.core
.Ed
changes the value for the sysctl process itself, and will not have the desired
effect.
.Pp
To create the root of a new sub-tree called
.Dq local
add some children to the new node, and some descriptions:
.Bd -literal -offset indent -compact
sysctl -w //create=local
sysctl -w //describe=local=my local sysctl tree
sysctl -w //create=local.esm_debug,type=int,symbol=esm_debug,flags=w
sysctl -w //describe=local.esm_debug=esm driver debug knob
sysctl -w //create=local.audiodebug,type=int,symbol=audiodebug,flags=w
sysctl -w //describe=local.audiodebug=generic audio debug knob
.Ed
Note that the children are made writable so that the two debug
settings in question can be tuned arbitrarily.
.Pp
To destroy that same subtree:
.Bd -literal -offset indent -compact
sysctl -w //destroy=local.esm_debug
sysctl -w //destroy=local.audiodebug
sysctl -w //destroy=local
.Ed
.Sh SEE ALSO
.Xr sysctl 3 ,
.Xr ksyms 4
.Sh HISTORY
.Nm sysctl
first appeared in
.Bx 4.4 .