305 lines
10 KiB
Groff
305 lines
10 KiB
Groff
.\"
|
|
.\" Copyright (c) 2006 Robert N. M. Watson
|
|
.\" 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.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 23, 2006
|
|
.Dt SYSCTL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm SYSCTL_DECL ,
|
|
.Nm SYSCTL_INT ,
|
|
.Nm SYSCTL_LONG ,
|
|
.Nm SYSCTL_NODE ,
|
|
.Nm SYSCTL_OPAQUE ,
|
|
.Nm SYSCTL_PROC ,
|
|
.Nm SYSCTL_STRING ,
|
|
.Nm SYSCTL_STRUCT ,
|
|
.Nm SYSCTL_UINT ,
|
|
.Nm SYSCTL_ULONG ,
|
|
.Nm SYSCTL_XINT ,
|
|
.Nm SYSCTL_XLONG
|
|
.Nd Static sysctl declaration functions
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/sysctl.h
|
|
.Fn SYSCTL_DECL name
|
|
.Fn SYSCTL_INT parent nbr name access ptr val descr
|
|
.Fn SYSCTL_LONG parent nbr name access ptr val descr
|
|
.Fn SYSCTL_NODE parent nbr name access handler descr
|
|
.Fn SYSCTL_OPAQUE parent nbr name access ptr len fmt descr
|
|
.Fn SYSCTL_PROC parent nbr name access ptr arg handler fmt descr
|
|
.Fn SYSCTL_STRING parent nbr name access arg len descr
|
|
.Fn SYSCTL_STRUCT parent nbr name access ptr type descr
|
|
.Fn SYSCTL_UINT parent nbr name access ptr val descr
|
|
.Fn SYSCTL_ULONG parent nbr name access ptr val descr
|
|
.Fn SYSCTL_XINT parent nbr name access ptr val descr
|
|
.Fn SYSCTL_XLONG parent nbr name access ptr val descr
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm SYSCTL
|
|
kernel interfaces allow code to statically declare
|
|
.Xr sysctl 8
|
|
MIB entries, which will be initialized when the kernel module containing the
|
|
declaration is initialized.
|
|
When the module is unloaded, the sysctl will be automatically destroyed.
|
|
.Pp
|
|
Sysctl nodes are created in a hierarchical tree, with all static nodes being
|
|
represented by named C data structures; in order to create a new node under
|
|
an existing node in the tree, the structure representing the desired parent
|
|
node must be declared in the current context using
|
|
.Fn SYSCTL_DECL .
|
|
.Pp
|
|
New nodes are declared using one of
|
|
.Fn SYSCTL_INT ,
|
|
.Fn SYSCTL_LONG ,
|
|
.Fn SYSCTL_NODE ,
|
|
.Fn SYSCTL_OPAQUE ,
|
|
.Fn SYSCTL_PROC ,
|
|
.Fn SYSCTL_STRING ,
|
|
.Fn SYSCTL_STRUCT ,
|
|
.Fn SYSCTL_UINT ,
|
|
.Fn SYSCTL_ULONG ,
|
|
.Fn SYSCTL_XINT ,
|
|
and
|
|
.Fn SYSCTL_XLONG .
|
|
Each macro accepts a parent name, as declared using
|
|
.Fn SYSCTL_DECL ,
|
|
an OID number, typically
|
|
.Dv OID_AUTO ,
|
|
a node name, a set of control and access flags, and a description.
|
|
Depending on the macro, a pointer to a variable supporting the MIB entry, a
|
|
size, a value, and a function pointer implementing the MIB entry may also be
|
|
present.
|
|
.Pp
|
|
For most of the above macros, declaring a type as part of the access flags is
|
|
not necessary \[em] however, when declaring a sysctl implemented by a function,
|
|
including a type in the access mask is required:
|
|
.Bl -tag -width ".Dv CTLTYPE_STRING"
|
|
.It Dv CTLTYPE_NODE
|
|
This is a node intended to be a parent for other nodes.
|
|
.It Dv CTLTYPE_INT
|
|
This is a signed integer.
|
|
.It Dv CTLTYPE_STRING
|
|
This is a nul-terminated string stored in a character array.
|
|
.It Dv CTLTYPE_QUAD
|
|
This is a 64-bit signed integer.
|
|
.It Dv CTLTYPE_OPAQUE
|
|
This is an opaque data structure.
|
|
.It Dv CTLTYPE_STRUCT
|
|
Alias for
|
|
.Dv CTLTYPE_OPAQUE.
|
|
.It Dv CTLTYPE_UINT
|
|
This is an unsigned integer.
|
|
.It Dv CTLTYPE_LONG
|
|
This is a signed long.
|
|
.It Dv CTLTYPE_ULONG
|
|
This is an unsigned long.
|
|
.El
|
|
.Pp
|
|
All sysctl types except for new node declarations require one or more flags
|
|
to be set indicating the read and write disposition of the sysctl:
|
|
.Bl -tag -width ".Dv CTLFLAG_ANYBODY"
|
|
.It Dv CTLFLAG_RD
|
|
This is a read-only sysctl.
|
|
.It Dv CTLFLAG_WR
|
|
This is a writable sysctl.
|
|
.It Dv CTLFLAG_RW
|
|
This sysctl is readable and writable.
|
|
.It Dv CTLFLAG_ANYBODY
|
|
Any user or process can write to this sysctl.
|
|
.It Dv CTLFLAG_SECURE
|
|
This sysctl can be written to only if the effective securelevel of the
|
|
process is \[<=] 0.
|
|
.It Dv CTLFLAG_PRISON
|
|
This sysctl can be written to by processes in
|
|
.Xr jail 2 .
|
|
.It Dv CTLFLAG_SKIP
|
|
When iterating the sysctl name space, do not list this sysctl.
|
|
.It Dv CTLFLAG_TUN
|
|
Also declare a system tunable with the same name to initialize this variable.
|
|
.It Dv CTLFLAG_RDTUN
|
|
Also declare a system tunable with the same name to initialize this variable;
|
|
however, the run-time variable is read-only.
|
|
.El
|
|
.Pp
|
|
When creating new sysctls, careful attention should be paid to the security
|
|
implications of the monitoring or management interface being created.
|
|
Most sysctls present in the kernel are read-only or writable only by the
|
|
superuser.
|
|
Sysctls exporting extensive information on system data structures and
|
|
operation, especially those implemented using procedures, will wish to
|
|
implement access control to limit the undesired exposure of information about
|
|
other processes, network connections, etc.
|
|
.Pp
|
|
The following top level sysctl name spaces are commonly used:
|
|
.Bl -tag -width ".Va regression"
|
|
.It Va compat
|
|
Compatibility layer information.
|
|
.It Va debug
|
|
Debugging information.
|
|
Various name spaces exist under
|
|
.Va debug .
|
|
.It Va hw
|
|
Hardware and device driver information.
|
|
.It Va kern
|
|
Kernel behavior tuning; generally deprecated in favor of more specific
|
|
name spaces.
|
|
.It Va machdep
|
|
Machine-dependent configuration parameters.
|
|
.It Va net
|
|
Network subsystem.
|
|
Various protocols have name spaces under
|
|
.Va net .
|
|
.It Va regression
|
|
Regression test configuration and information.
|
|
.It Va security
|
|
Security and security-policy configuration and information.
|
|
.It Va sysctl
|
|
Reserved name space for the implementation of sysctl.
|
|
.It Va user
|
|
Configuration settings relating to user application behavior.
|
|
Generally, configuring applications using kernel sysctls is discouraged.
|
|
.It Va vfs
|
|
Virtual file system configuration and information.
|
|
.It Va vm
|
|
Virtual memory subsystem configuration and information.
|
|
.El
|
|
.Sh EXAMPLES
|
|
Sample use of
|
|
.Fn SYSCTL_DECL
|
|
to declare the
|
|
.Va security
|
|
sysctl tree for use by new nodes:
|
|
.Bd -literal -offset indent
|
|
SYSCTL_DECL(_security);
|
|
.Ed
|
|
.Pp
|
|
Examples of integer, opaque, string, and procedure sysctls follow:
|
|
.Bd -literal -offset indent
|
|
/*
|
|
* Example of a constant integer value. Notice that the control
|
|
* flags are CTLFLAG_RD, the variable pointer is NULL, and the
|
|
* value is declared.
|
|
* If sysctl(8) should print this value in hex, use 'SYSCTL_XINT'.
|
|
*/
|
|
SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, NULL,
|
|
sizeof(struct bio), "sizeof(struct bio)");
|
|
|
|
/*
|
|
* Example of a variable integer value. Notice that the control
|
|
* flags are CTLFLAG_RW, the variable pointer is set, and the
|
|
* value is 0.
|
|
*/
|
|
static int doingcache = 1; /* 1 => enable the cache */
|
|
SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
|
|
"Enable name cache");
|
|
|
|
/*
|
|
* Example of a variable string value. Notice that the control
|
|
* flags are CTLFLAG_RW, that the variable pointer and string
|
|
* size are set. Unlike newer sysctls, this older sysctl uses a
|
|
* static oid number.
|
|
*/
|
|
char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */
|
|
SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
|
|
kernelname, sizeof(kernelname), "Name of kernel file booted");
|
|
|
|
/*
|
|
* Example of an opaque data type exported by sysctl. Notice that
|
|
* the variable pointer and size are provided, as well as a format
|
|
* string for sysctl(8).
|
|
*/
|
|
static l_fp pps_freq; /* scaled frequence offset (ns/s) */
|
|
SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
|
|
&pps_freq, sizeof(pps_freq), "I", "");
|
|
|
|
/*
|
|
* Example of a procedure based sysctl exporting string
|
|
* information. Notice that the data type is declared, the NULL
|
|
* variable pointer and 0 size, the function pointer, and the
|
|
* format string for sysctl(8).
|
|
*/
|
|
SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
|
|
CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
|
|
"");
|
|
.Ed
|
|
.Sh SYSCTL NAMING
|
|
When adding, modifying, or removing sysctl names, it is important to be
|
|
aware that these interfaces may be used by users, libraries, applications,
|
|
or documentation (such as published books), and are implicitly published application interfaces.
|
|
As with other application interfaces, caution must be taken not to break
|
|
existing applications, and to think about future use of new name spaces so as
|
|
to avoid the need to rename or remove interfaces that might be depended on in
|
|
the future.
|
|
.Pp
|
|
The semantics chosen for a new sysctl should be as clear as possible,
|
|
and the name of the sysctl must closely reflect its semantics.
|
|
Therefore the sysctl name deserves a fair amount of consideration.
|
|
It should be short but yet representative of the sysctl meaning.
|
|
If the name consists of several words, they should be separated by
|
|
underscore characters, as in
|
|
.Va compute_summary_at_mount .
|
|
Underscore characters may be omitted only if the name consists of not more
|
|
than two words, each being not longer than four characters, as in
|
|
.Va bootfile .
|
|
For boolean sysctls, negative logic should be totally avoided.
|
|
That is, do not use names like
|
|
.Va no_foobar
|
|
or
|
|
.Va foobar_disable .
|
|
They are confusing and lead to configuration errors.
|
|
Use positive logic instead:
|
|
.Va foobar ,
|
|
.Va foobar_enable .
|
|
.Pp
|
|
A temporary sysctl node that should not be relied upon must be designated
|
|
as such by a leading underscore character in its name. For example:
|
|
.Va _dirty_hack .
|
|
.Sh SEE ALSO
|
|
.Xr sysctl 8 ,
|
|
.Xr sysctl_add_oid 9 ,
|
|
.Xr sysctl_ctx_free 9 ,
|
|
.Xr sysctl_ctx_init 9 ,
|
|
.Xr sysctl_remove_oid 9
|
|
.Sh HISTORY
|
|
The
|
|
.Xr sysctl 8
|
|
utility first appeared in
|
|
.Bx 4.4 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm sysctl
|
|
implementation originally found in
|
|
.Bx
|
|
has been extensively rewritten by
|
|
.An Poul-Henning Kamp
|
|
in order to add support for name lookups, name space iteration, and dynamic
|
|
addition of MIB nodes.
|
|
.Pp
|
|
This man page was written by
|
|
.An Robert N. M. Watson .
|