2 .\" Copyright (c) 2006 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nm SYSCTL_ADD_NODE_WITH_LABEL ,
37 .Nm SYSCTL_ADD_OPAQUE ,
40 .Nm SYSCTL_ADD_ROOT_NODE ,
45 .Nm SYSCTL_ADD_STRING ,
46 .Nm SYSCTL_ADD_STRUCT ,
51 .Nm SYSCTL_ADD_UAUTO ,
53 .Nm SYSCTL_ADD_ULONG ,
54 .Nm SYSCTL_ADD_UQUAD ,
56 .Nm SYSCTL_STATIC_CHILDREN ,
57 .Nm SYSCTL_NODE_CHILDREN ,
60 .Nm SYSCTL_INT_WITH_LABEL ,
63 .Nm SYSCTL_NODE_WITH_LABEL ,
67 .Nm SYSCTL_ROOT_NODE ,
81 .Nd Dynamic and static sysctl MIB creation functions
86 .Ft struct sysctl_oid *
88 .Fa "struct sysctl_ctx_list *ctx"
89 .Fa "struct sysctl_oid_list *parent"
91 .Fa "const char *name"
95 .Fa "const char *descr"
97 .Ft struct sysctl_oid *
99 .Fa "struct sysctl_ctx_list *ctx"
100 .Fa "struct sysctl_oid_list *parent"
102 .Fa "const char *name"
105 .Fa "const char *descr"
107 .Ft struct sysctl_oid *
109 .Fa "struct sysctl_ctx_list *ctx"
110 .Fa "struct sysctl_oid_list *parent"
112 .Fa "const char *name"
114 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
115 .Fa "const char *descr"
117 .Ft struct sysctl_oid *
118 .Fo SYSCTL_ADD_NODE_WITH_LABEL
119 .Fa "struct sysctl_ctx_list *ctx"
120 .Fa "struct sysctl_oid_list *parent"
122 .Fa "const char *name"
124 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
125 .Fa "const char *descr"
126 .Fa "const char *label"
128 .Ft struct sysctl_oid *
129 .Fo SYSCTL_ADD_OPAQUE
130 .Fa "struct sysctl_ctx_list *ctx"
131 .Fa "struct sysctl_oid_list *parent"
133 .Fa "const char *name"
137 .Fa "const char *format"
138 .Fa "const char *descr"
140 .Ft struct sysctl_oid *
142 .Fa "struct sysctl_ctx_list *ctx"
143 .Fa "struct sysctl_oid_list *parent"
145 .Fa "const char *name"
149 .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
150 .Fa "const char *format"
151 .Fa "const char *descr"
153 .Ft struct sysctl_oid *
155 .Fa "struct sysctl_ctx_list *ctx"
156 .Fa "struct sysctl_oid_list *parent"
158 .Fa "const char *name"
161 .Fa "const char *descr"
163 .Ft struct sysctl_oid *
164 .Fo SYSCTL_ADD_ROOT_NODE
165 .Fa "struct sysctl_ctx_list *ctx"
167 .Fa "const char *name"
169 .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
170 .Fa "const char *descr"
172 .Ft struct sysctl_oid *
174 .Fa "struct sysctl_ctx_list *ctx"
175 .Fa "struct sysctl_oid_list *parent"
177 .Fa "const char *name"
181 .Fa "const char *descr"
183 .Ft struct sysctl_oid *
185 .Fa "struct sysctl_ctx_list *ctx"
186 .Fa "struct sysctl_oid_list *parent"
188 .Fa "const char *name"
192 .Fa "const char *descr"
194 .Ft struct sysctl_oid *
196 .Fa "struct sysctl_ctx_list *ctx"
197 .Fa "struct sysctl_oid_list *parent"
199 .Fa "const char *name"
203 .Fa "const char *descr"
205 .Ft struct sysctl_oid *
207 .Fa "struct sysctl_ctx_list *ctx"
208 .Fa "struct sysctl_oid_list *parent"
210 .Fa "const char *name"
214 .Fa "const char *descr"
216 .Ft struct sysctl_oid *
217 .Fo SYSCTL_ADD_STRING
218 .Fa "struct sysctl_ctx_list *ctx"
219 .Fa "struct sysctl_oid_list *parent"
221 .Fa "const char *name"
225 .Fa "const char *descr"
227 .Ft struct sysctl_oid *
228 .Fo SYSCTL_ADD_STRUCT
229 .Fa "struct sysctl_ctx_list *ctx"
230 .Fa "struct sysctl_oid_list *parent"
232 .Fa "const char *name"
236 .Fa "const char *descr"
238 .Ft struct sysctl_oid *
240 .Fa "struct sysctl_ctx_list *ctx"
241 .Fa "struct sysctl_oid_list *parent"
243 .Fa "const char *name"
247 .Fa "const char *descr"
249 .Ft struct sysctl_oid *
251 .Fa "struct sysctl_ctx_list *ctx"
252 .Fa "struct sysctl_oid_list *parent"
254 .Fa "const char *name"
258 .Fa "const char *descr"
260 .Ft struct sysctl_oid *
262 .Fa "struct sysctl_ctx_list *ctx"
263 .Fa "struct sysctl_oid_list *parent"
265 .Fa "const char *name"
269 .Fa "const char *descr"
271 .Ft struct sysctl_oid *
273 .Fa "struct sysctl_ctx_list *ctx"
274 .Fa "struct sysctl_oid_list *parent"
276 .Fa "const char *name"
280 .Fa "const char *descr"
282 .Ft struct sysctl_oid *
284 .Fa "struct sysctl_ctx_list *ctx"
285 .Fa "struct sysctl_oid_list *parent"
287 .Fa "const char *name"
289 .Fa "unsigned int *ptr"
290 .Fa "unsigned int val"
291 .Fa "const char *descr"
293 .Ft struct sysctl_oid *
295 .Fa "struct sysctl_ctx_list *ctx"
296 .Fa "struct sysctl_oid_list *parent"
298 .Fa "const char *name"
300 .Fa "unsigned long *ptr"
301 .Fa "const char *descr"
303 .Ft struct sysctl_oid *
305 .Fa "struct sysctl_ctx_list *ctx"
306 .Fa "struct sysctl_oid_list *parent"
308 .Fa "const char *name"
311 .Fa "const char *descr"
313 .Ft struct sysctl_oid *
315 .Fa "struct sysctl_ctx_list *ctx"
316 .Fa "struct sysctl_oid_list *parent"
318 .Fa "const char *name"
321 .Fa "const char *descr"
323 .Ft struct sysctl_oid_list *
325 .Fa "struct sysctl_oid *oidp"
327 .Ft struct sysctl_oid_list *
328 .Fo SYSCTL_STATIC_CHILDREN
329 .Fa "struct sysctl_oid_list OID_NAME"
331 .Ft struct sysctl_oid_list *
332 .Fo SYSCTL_NODE_CHILDREN
336 .Ft struct sysctl_oid *
338 .Fa "struct sysctl_oid *oid"
340 .Fn SYSCTL_INT parent number name ctlflags ptr val descr
341 .Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label
342 .Fn SYSCTL_LONG parent number name ctlflags ptr val descr
343 .Fn SYSCTL_NODE parent number name ctlflags handler descr
344 .Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label
345 .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
346 .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr
347 .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr
348 .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr
349 .Fn SYSCTL_S8 parent number name ctlflags ptr val descr
350 .Fn SYSCTL_S16 parent number name ctlflags ptr val descr
351 .Fn SYSCTL_S32 parent number name ctlflags ptr val descr
352 .Fn SYSCTL_S64 parent number name ctlflags ptr val descr
353 .Fn SYSCTL_STRING parent number name ctlflags arg len descr
354 .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr
355 .Fn SYSCTL_U8 parent number name ctlflags ptr val descr
356 .Fn SYSCTL_U16 parent number name ctlflags ptr val descr
357 .Fn SYSCTL_U32 parent number name ctlflags ptr val descr
358 .Fn SYSCTL_U64 parent number name ctlflags ptr val descr
359 .Fn SYSCTL_UINT parent number name ctlflags ptr val descr
360 .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr
361 .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr
365 kernel interface allows dynamic or static creation of
368 All static sysctls are automatically destroyed when the module which
369 they are part of is unloaded.
370 Most top level categories are created statically and are available to
371 all kernel code and its modules.
372 .Sh DESCRIPTION OF ARGUMENTS
373 .Bl -tag -width ctlflags
375 Pointer to sysctl context or NULL, if no context.
377 .Xr sysctl_ctx_init 9
378 for how to create a new sysctl context.
379 Programmers are strongly advised to use contexts to organize the
380 dynamic OIDs which they create because when a context is destroyed all
381 belonging sysctls are destroyed as well.
382 This makes the sysctl cleanup code much simpler.
383 Else deletion of all created OIDs is required at module unload.
386 .Li struct sysctl_oid_list ,
387 which is the head of the parent's list of children.
388 This pointer is retrieved using the
389 .Fn SYSCTL_STATIC_CHILDREN
390 macro for static sysctls and the
392 macro for dynamic sysctls.
395 macro can be used to get the parent of an OID.
396 The macro returns NULL if there is no parent.
398 The OID number that will be assigned to this OID.
399 In almost all cases this should be set to
401 which will result in the assignment of the next available OID number.
404 The newly created OID will contain a copy of the name.
406 A bit mask of sysctl control flags.
407 See the section below describing all the control flags.
409 First callback argument for procedure sysctls.
411 Second callback argument for procedure sysctls.
413 The length of the data pointed to by the
416 For string type OIDs a length of zero means that
418 will be used to get the length of the string at each access to the OID.
420 Pointer to sysctl variable or string data.
421 For sysctl values the pointer can be SYSCTL_NULL_XXX_PTR which means the OID is read-only and the returned value should be taken from the
427 argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID.
428 Else this argument is not used.
430 Name of structure type.
432 A pointer to the function
433 that is responsible for handling read and write requests
435 There are several standard handlers
436 that support operations on nodes,
437 integers, strings and opaque objects.
438 It is possible to define custom handlers using the
444 A pointer to a string
445 which specifies the format of the OID in a symbolic way.
446 This format is used as a hint by
448 to apply proper data formatting for display purposes.
451 .Bl -tag -width "S,TYPE" -compact -offset indent
459 temperature in Kelvin, multiplied by an optional single digit
460 power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3
477 A pointer to a textual description of the OID.
479 A pointer to an aggregation label for this component of the OID.
480 To make it easier to export sysctl data to monitoring systems that
481 support aggregations through labels (e.g., Prometheus),
482 this argument can be used to attach a label name to an OID.
483 The label acts as a hint that this component's name should not be part
484 of the metric's name,
485 but attached to the metric as a label instead.
487 Labels should only be applied to siblings that are structurally similar
488 and encode the same type of value,
489 as aggregation is of no use otherwise.
491 .Sh CREATING ROOT NODES
492 Sysctl MIBs or OIDs are created in a hierarchical tree.
493 The nodes at the bottom of the tree are called root nodes, and have no
495 To create bottom tree nodes the
498 .Fn SYSCTL_ADD_ROOT_NODE
499 function needs to be used.
500 By default all static sysctl node OIDs are global and need a
502 statement prior to their
504 definition statement, typically in a so-called header file.
505 .Sh CREATING SYSCTL STRINGS
506 Zero terminated character strings sysctls are created either using the
509 .Fn SYSCTL_ADD_STRING
513 argument in zero, the string length is computed at every access to the OID using
515 .Sh CREATING OPAQUE SYSCTLS
521 .Fn SYSCTL_ADD_OPAQUE
523 .Fn SYSCTL_ADD_STRUCT
524 functions create an OID that handle any chunk of data
525 of the size specified by the
527 argument and data pointed to by the
530 When using the structure version the type is encoded as part of the
532 .Sh CREATING CUSTOM SYSCTLS
538 create OIDs with the specified
541 The handler is responsible for handling all read and write requests to
543 This OID type is especially useful if the kernel data is not easily
544 accessible, or needs to be processed before exporting.
545 .Sh CREATING A STATIC SYSCTL
546 Static sysctls are declared using one of the
548 .Fn SYSCTL_INT_WITH_LABEL ,
551 .Fn SYSCTL_NODE_WITH_LABEL ,
555 .Fn SYSCTL_ROOT_NODE ,
571 .Sh CREATING A DYNAMIC SYSCTL
572 Dynamic nodes are created using one of the
574 .Fn SYSCTL_ADD_LONG ,
575 .Fn SYSCTL_ADD_NODE ,
576 .Fn SYSCTL_ADD_NODE_WITH_LABEL ,
577 .Fn SYSCTL_ADD_OPAQUE ,
578 .Fn SYSCTL_ADD_PROC ,
579 .Fn SYSCTL_ADD_QUAD ,
580 .Fn SYSCTL_ADD_ROOT_NODE ,
585 .Fn SYSCTL_ADD_STRING ,
586 .Fn SYSCTL_ADD_STRUCT ,
591 .Fn SYSCTL_ADD_UAUTO ,
592 .Fn SYSCTL_ADD_UINT ,
593 .Fn SYSCTL_ADD_ULONG ,
598 .Xr sysctl_remove_oid 9
600 .Xr sysctl_ctx_free 9
601 for more information on how to destroy a dynamically created OID.
603 For most of the above functions and macros, declaring a type as part
604 of the access flags is not necessary \[em] however, when declaring a
605 sysctl implemented by a function, including a type in the access mask
607 .Bl -tag -width ".Dv CTLTYPE_NOFETCH"
609 This is a node intended to be a parent for other nodes.
611 This is a signed integer.
612 .It Dv CTLTYPE_STRING
613 This is a nul-terminated string stored in a character array.
615 This is an 8-bit signed integer.
617 This is a 16-bit signed integer.
619 This is a 32-bit signed integer.
621 This is a 64-bit signed integer.
622 .It Dv CTLTYPE_OPAQUE
623 This is an opaque data structure.
624 .It Dv CTLTYPE_STRUCT
628 This is an 8-bit unsigned integer.
630 This is a 16-bit unsigned integer.
632 This is a 32-bit unsigned integer.
634 This is a 64-bit unsigned integer.
636 This is an unsigned integer.
638 This is a signed long.
640 This is an unsigned long.
643 All sysctl types except for new node declarations require one of the following
644 flags to be set indicating the read and write disposition of the sysctl:
645 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
647 This is a read-only sysctl.
649 This is a read-only sysctl and tunable which is tried fetched once
650 from the system environment early during module load or system boot.
652 This is a writable sysctl.
654 This sysctl is readable and writable.
656 This is a readable and writeable sysctl and tunable which is tried
657 fetched once from the system environment early during module load or
659 .It Dv CTLFLAG_NOFETCH
660 In case the node is marked as a tunable using the CTLFLAG_[XX]TUN,
661 this flag will prevent fetching the initial value from the system
663 Typically this flag should only be used for very early
664 low level system setup code, and not by common drivers and modules.
667 Additionally, any of the following optional flags may also be specified:
668 .Bl -tag -width ".Dv CTLFLAG_ANYBODY"
669 .It Dv CTLFLAG_ANYBODY
670 Any user or process can write to this sysctl.
671 .It Dv CTLFLAG_SECURE
672 This sysctl can be written to only if the effective securelevel of the
674 .It Dv CTLFLAG_PRISON
675 This sysctl can be written to by processes in
678 When iterating the sysctl name space, do not list this sysctl.
680 Advisory flag that a system tunable also exists for this variable.
681 The initial sysctl value is tried fetched once from the system
682 environment early during module load or system boot.
684 Dynamically created OIDs automatically get this flag set.
686 OID references a VIMAGE-enabled variable.
693 sysctl tree for use by new nodes:
694 .Bd -literal -offset indent
695 SYSCTL_DECL(_security);
698 Examples of integer, opaque, string, and procedure sysctls follow:
699 .Bd -literal -offset indent
701 * Example of a constant integer value. Notice that the control
702 * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR,
703 * and the value is declared.
705 SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR,
706 sizeof(struct bio), "sizeof(struct bio)");
709 * Example of a variable integer value. Notice that the control
710 * flags are CTLFLAG_RW, the variable pointer is set, and the
713 static int doingcache = 1; /* 1 => enable the cache */
714 SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0,
715 "Enable name cache");
718 * Example of a variable string value. Notice that the control
719 * flags are CTLFLAG_RW, that the variable pointer and string
720 * size are set. Unlike newer sysctls, this older sysctl uses a
723 char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */
724 SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW,
725 kernelname, sizeof(kernelname), "Name of kernel file booted");
728 * Example of an opaque data type exported by sysctl. Notice that
729 * the variable pointer and size are provided, as well as a format
730 * string for sysctl(8).
732 static l_fp pps_freq; /* scaled frequency offset (ns/s) */
733 SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD,
734 &pps_freq, sizeof(pps_freq), "I", "");
737 * Example of a procedure based sysctl exporting string
738 * information. Notice that the data type is declared, the NULL
739 * variable pointer and 0 size, the function pointer, and the
740 * format string for sysctl(8).
742 SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING |
743 CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A",
747 The following is an example of
748 how to create a new top-level category
749 and how to hook up another subtree to an existing static node.
750 This example does not use contexts,
751 which results in tedious management of all intermediate oids,
752 as they need to be freed later on:
753 .Bd -literal -offset indent
754 #include <sys/sysctl.h>
757 * Need to preserve pointers to newly created subtrees,
758 * to be able to free them later:
760 static struct sysctl_oid *root1;
761 static struct sysctl_oid *root2;
762 static struct sysctl_oid *oidp;
764 static char *string = "dynamic sysctl";
767 root1 = SYSCTL_ADD_ROOT_NODE(NULL,
768 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
769 oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1),
770 OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
772 root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug),
773 OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
774 oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2),
775 OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
778 This example creates the following subtrees:
779 .Bd -literal -offset indent
780 debug.newtree.newstring
784 .Em "Care should be taken to free all OIDs once they are no longer needed!"
786 When adding, modifying, or removing sysctl names, it is important to be
787 aware that these interfaces may be used by users, libraries, applications,
788 or documentation (such as published books), and are implicitly published application interfaces.
789 As with other application interfaces, caution must be taken not to break
790 existing applications, and to think about future use of new name spaces so as
791 to avoid the need to rename or remove interfaces that might be depended on in
794 The semantics chosen for a new sysctl should be as clear as possible,
795 and the name of the sysctl must closely reflect its semantics.
796 Therefore the sysctl name deserves a fair amount of consideration.
797 It should be short but yet representative of the sysctl meaning.
798 If the name consists of several words, they should be separated by
799 underscore characters, as in
800 .Va compute_summary_at_mount .
801 Underscore characters may be omitted only if the name consists of not more
802 than two words, each being not longer than four characters, as in
804 For boolean sysctls, negative logic should be totally avoided.
805 That is, do not use names like
809 They are confusing and lead to configuration errors.
810 Use positive logic instead:
814 A temporary sysctl node OID that should not be relied upon must be designated
815 as such by a leading underscore character in its name.
821 .Xr sysctl_add_oid 9 ,
822 .Xr sysctl_ctx_free 9 ,
823 .Xr sysctl_ctx_init 9 ,
824 .Xr sysctl_remove_oid 9
828 utility first appeared in
834 implementation originally found in
836 has been extensively rewritten by
837 .An Poul-Henning Kamp
838 in order to add support for name lookups, name space iteration, and dynamic
839 addition of MIB nodes.
841 This man page was written by
842 .An Robert N. M. Watson .
843 .Sh SECURITY CONSIDERATIONS
844 When creating new sysctls, careful attention should be paid to the security
845 implications of the monitoring or management interface being created.
846 Most sysctls present in the kernel are read-only or writable only by the
848 Sysctls exporting extensive information on system data structures and
849 operation, especially those implemented using procedures, will wish to
850 implement access control to limit the undesired exposure of information about
851 other processes, network connections, etc.
853 The following top level sysctl name spaces are commonly used:
854 .Bl -tag -width ".Va regression"
856 Compatibility layer information.
858 Debugging information.
859 Various name spaces exist under
862 Hardware and device driver information.
864 Kernel behavior tuning; generally deprecated in favor of more specific
867 Machine-dependent configuration parameters.
870 Various protocols have name spaces under
873 Regression test configuration and information.
875 Security and security-policy configuration and information.
877 Reserved name space for the implementation of sysctl.
879 Configuration settings relating to user application behavior.
880 Generally, configuring applications using kernel sysctls is discouraged.
882 Virtual file system configuration and information.
884 Virtual memory subsystem configuration and information.