Manual nsysctl version 2

Posted on 2021-03-07 - Updated on 2025-06-28

The nsysctl utility allows you to get or set the FreeBSD kernel state at runtime. This post serves as the manual; a tutorial is also available.

NSYSCTL(8)              FreeBSD System Manager's Manual             NSYSCTL(8)

NAME
     nsysctl - get or set system state

SYNOPSIS
     nsysctl [--libxo options [-r tagroot]] [-DdeFGgHIiJLnOpqTtVvWz]
             [-N | -hl [b | o | x]] [-B bufsize] [-f filename] [-j jailname]
             [-s sep] name[=value[,value]] ...
     nsysctl [--libxo options [-r tagroot]] [-DdeFGgHIJkLnOpqSTtVvWz]
             [-N | -hlu [b | o | x]] [-B bufsize] [-f filename] [-j jailname]
             [-s sep] -a

DESCRIPTION
     The nsysctl utility is used to get or set the state of the system at
     runtime.

     The system exposes the available parameters as objects in a "Management
     Information Base" (MIB).  nsysctl can explore the MIB, print object
     properties, retrieve or update their values, and display the output in
     both human and machine readable formats.

     Each object is identified by an "Object Identifier" (OID), which is a
     sequence of numbers.  Numbers can be replaced with strings to form the
     object name.  For example, "1.1" can be expressed as "kern.ostype".

     nsysctl accepts one or more object names, optionally followed by a new
     value.  Alternatively, the -a flag can be used to display all available
     objects.

     nsysctl requires the sysctlinfo(4) interface.  To load the required
     kernel module at boot time, place the following line in loader.conf(5):

           sysctlinfo_load="YES"

     The following options are available:

     --libxo options
             Generate output using libxo(3) in a variety of human and machine
             readable formats.  See xo_parse_args(3) for supported options.

     -A      Equivalent to -a -o.  This option is obsolete.

     -a      Display all objects.

     -b      Print values in binary format.

     -B bufsize
             Use a buffer of bufsize bytes.

     -D      Equivalent to -d -F -G -H -L -O -t.

     -d      Show object descriptions.

     -e      Use "=" as a key-value separator.

     -F      Display the format string of each object.

     -f filename
             Load object names from filename.

     -G      Show flags with their true (internal) values.

     -g      Display flags associated with each object.

     -H      Show the handler status of each object.

     -h      Attempt to display values in a human-friendly format.

     -I      Include internal nodes in the output.  By default, only leaf
             nodes are shown.

     -i      Ignore unknown objects.

     -J      Show only objects flagged with PRISON.  See jail(2) for details.

     -j jailname
             Attach to the jail named jailname.  See jail(2) and jls(8) for
             details.  nsysctl initializes libxo(3), parses command-line
             options, and attaches to the specified jail immediately
             afterward.  Any file specified with the -f option is read within
             the context of jailname.  See jexec(8) for additional jail
             execution methods.

     -k      Include objects marked with the SKIP flag when used with -a.

     -L      Display the aggregation label.

     -l      Display the size of the value in bytes.

     -N      Suppress value output.

     -n      Suppress name output.

     -O      Display the Object Identifier (OID).

     -o      Display values in hexadecimal format, up to 16 bytes.

     -p      Display property output in the format: "[PROPERTY-NAME]:
             property-value".

     -q      Suppress certain warnings.

     -r tagroot
             Specify a tagroot for use with libxo(3).

     -S      Also display the "sysctl.*" subtree when used with -a.

     -s sep  Use sep as a separator.

     -T      Show only objects that are settable via the loader.

     -t      Display the type of each object.

     -u      By default, -a hides objects without a value.  This option
             disables that behavior.

     -V      Show only objects relevant to network subsystem virtualization,
             flagged with VNET.  See vnet(9) for details.

     -v      Display the nsysctl version and exit.

     -W      Show only writable objects that are not marked as statistical.

     -X      Equivalent to -a -x.  This option is obsolete.

     -x      Display values in hexadecimal format.

     -z      Toggle the numeric or boolean value.  A value of 0 becomes 1, and
             any non-zero value becomes 0.  Only the first element of an array
             is modified.

EXIT STATUS
     The nsysctl utility exits 0 on success, and >0 if an error occurs.

EXAMPLES
     To retrieve the value of an object:

           % nsysctl kern.hostname

     To set the value of an object:

           % nsysctl kern.hostname=myBSD

     To display detailed information about an object:

           % nsysctl -pD kern.ostype

     To display object information in XML format:

           % nsysctl --libxo=xml,pretty -D kern.ostype

COMPATIBILITY
     sysctl(8) prints internal and SKIP nodes when used with -aN, -ad, or -at.
     Otherwise, it only prints leaf nodes, skipping those marked with SKIP.

     To reproduce the same behavior with nsysctl, use the following
     equivalents:
           /sbin/sysctl             /usr/local/sbin/nsysctl
           % sysctl -aN             % nsysctl -aNIk
           % sysctl -ad             % nsysctl -adIk
           % sysctl -at             % nsysctl -atIk

SEE ALSO
     jail(2), sysctl(3), sysctlmibinfo2(3), xo_parse_args(3), sysctlinfo(4),
     jexec(8), jls(8), sysctl(8)

AUTHORS
     nsysctl was written by Alfonso Sabato Siciliano <asiciliano@FreeBSD.org>.

FreeBSD 15.0-CURRENT             June 28, 2025            FreeBSD 15.0-CURRENT