sysctl.tproj/sysctl.8

   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
  46 The
  47 .Nm
  48 utility retrieves kernel state and allows processes with appropriate
  49 privilege to set kernel state.
  50 The state to be retrieved or set is described using a
  51 .Dq Management Information Base
  52 .Pq Dq MIB
  53 style name, described as a dotted set of
  54 components.
  55 .Pp
  56 The following options are available:
  57 .Bl -tag -width indent
  58 .It Fl A
  59 Equivalent to
  60 .Fl o a
  61 (for compatibility).
  62 .It Fl a
  63 List all the currently available non-opaque values.
  64 This option is ignored if one or more variable names are specified on
  65 the command line.
  66 .It Fl b
  67 Force the value of the variable(s) to be output in raw, binary format.
  68 No names are printed and no terminating newlines are output.
  69 This is mostly useful with a single variable.
  70 .It Fl d
  71 Print the description of the variable instead of its value.
  72 .It Fl e
  73 Separate the name and the value of the variable(s) with
  74 .Ql = .
  75 This is useful for producing output which can be fed back to the
  76 .Nm
  77 utility.
  78 This option is ignored if either
  79 .Fl N
  80 or
  81 .Fl n
  82 is specified, or a variable is being set.
  83 .It Fl h
  84 Format output for human, rather than machine, readability.
  85 .It Fl i
  86 Ignore unknown OIDs.
  87 The purpose is to make use of
  88 .Nm
  89 for collecting data from a variety of machines (not all of which
  90 are necessarily running exactly the same software) easier.
  91 .It Fl N
  92 Show only variable names, not their values.
  93 This is particularly useful with shells that offer programmable
  94 completion.
  95 To enable completion of variable names in
  96 .Xr zsh 1 Pq Pa ports/shells/zsh ,
  97 use the following code:
  98 .Bd -literal -offset indent
  99 listsysctls () { set -A reply $(sysctl -AN ${1%.*}) }
 100 compctl -K listsysctls sysctl
 101 .Ed
 102 .Pp
 103 To enable completion of variable names in
 104 .Xr tcsh 1 ,
 105 use:
 106 .Pp
 107 .Dl "complete sysctl 'n/*/`sysctl -Na`/'"
 108 .It Fl n
 109 Show only variable values, not their names.
 110 This option is useful for setting shell variables.
 111 For instance, to save the pagesize in variable
 112 .Va psize ,
 113 use:
 114 .Pp
 115 .Dl "set psize=`sysctl -n hw.pagesize`"
 116 .It Fl o
 117 Show opaque variables (which are normally suppressed).
 118 The format and length are printed, as well as a hex dump of the first
 119 sixteen bytes of the value.
 120 .It Fl q
 121 Suppress some warnings generated by
 122 .Nm
 123 to standard error.
 124 .It Fl X
 125 Equivalent to
 126 .Fl x a
 127 (for compatibility).
 128 .It Fl x
 129 As
 130 .Fl o ,
 131 but prints a hex dump of the entire value instead of just the first
 132 few bytes.
 133 .El
 134 .Pp
 135 The information available from
 136 .Nm
 137 consists of integers, strings, and opaque types.
 138 The
 139 .Nm
 140 utility
 141 only knows about a couple of opaque types, and will resort to hexdumps
 142 for the rest.
 143 The opaque information is much more useful if retrieved by special
 144 purpose programs such as
 145 .Xr ps 1 ,
 146 .Xr systat 1 ,
 147 and
 148 .Xr netstat 1 .
 149 .Pp
 150 .\" Some of the variables which cannot be modified during normal system
 151 .\" operation can be initialized via
 152 .\" .Xr loader 8
 153 .\" tunables.
 154 .\" This can for example be done by setting them in
 155 .\" .Xr loader.conf 5 .
 156 .\" Please refer to
 157 .\" .Xr loader.conf 5
 158 .\" for more information on which tunables are available and how to set them.
 159 .\" .Pp
 160 The string and integer information is summarized below.
 161 For a detailed description of these variable see
 162 .Xr sysctl 3 .
 163 .Pp
 164 The changeable column indicates whether a process with appropriate
 165 privilege can change the value.
 166 String and integer values can be set using
 167 .Nm .
 168 .Bl -column xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx integerxxx
 169 .It Sy "Name    Type    Changeable"
 170 .It "hw.activecpu       integer no"
 171 .It "hw.busfrequency    integer no"
 172 .It "hw.busfrequency_max        integer no"
 173 .It "hw.busfrequency_min        integer no"
 174 .It "hw.byteorder       integer no"
 175 .It "hw.cacheconfig     struct  no"
 176 .It "hw.cachelinesize   integer no"
 177 .It "hw.cachesize       struct  no"
 178 .It "hw.cpu64bit_capable        integer no"
 179 .It "hw.cpufamily       integer no"
 180 .It "hw.cpufrequency    integer no"
 181 .It "hw.cpufrequency_max        integer no"
 182 .It "hw.cpufrequency_min        integer no"
 183 .It "hw.cpusubtype      integer no"
 184 .It "hw.cputhreadtype   integer no"
 185 .It "hw.cputype integer no"
 186 .It "hw.l1dcachesize    integer no"
 187 .It "hw.l1icachesize    integer no"
 188 .It "hw.l2cachesize     integer no"
 189 .It "hw.l3cachesize     integer no"
 190 .It "hw.logicalcpu      integer no"
 191 .It "hw.logicalcpu_max  integer no"
 192 .It "hw.memsize integer no"
 193 .It "hw.ncpu    integer no"
 194 .It "hw.packages        integer no"
 195 .It "hw.pagesize        integer no"
 196 .It "hw.physicalcpu     integer no"
 197 .It "hw.physicalcpu_max integer no"
 198 .It "hw.tbfrequency     integer no"
 199 .It "kern.argmax        integer no"
 200 .It "kern.bootargs      string  no"
 201 .It "kern.boottime      struct  no"
 202 .It "kern.clockrate     struct  no"
 203 .It "kern.coredump      integer yes"
 204 .It "kern.corefile      string  yes"
 205 .It "kern.flush_cache_on_write  integer yes"
 206 .It "kern.hostid        integer yes"
 207 .It "kern.hostname      string  yes"
 208 .It "kern.job_control   integer no"
 209 .It "kern.maxfiles      integer yes"
 210 .It "kern.maxfilesperproc       integer yes"
 211 .It "kern.maxnbuf       integer yes"
 212 .It "kern.maxproc       integer yes"
 213 .It "kern.maxprocperuid integer yes"
 214 .It "kern.maxvnodes     integer yes"
 215 .It "kern.msgbuf        integer yes"
 216 .It "kern.nbuf  integer no"
 217 .It "kern.netboot       integer no"
 218 .It "kern.ngroups       integer no"
 219 .It "kern.nisdomainname string  yes"
 220 .It "kern.num_files     integer no"
 221 .It "kern.num_tasks     integer no"
 222 .It "kern.num_taskthreads       integer no"
 223 .It "kern.num_threads   integer no"
 224 .It "kern.num_vnodes    integer no"
 225 .It "kern.nx    integer yes"
 226 .It "kern.osrelease     string  no"
 227 .It "kern.osrevision    integer no"
 228 .It "kern.ostype        string  no"
 229 .It "kern.osversion     string  yes"
 230 .It "kern.posix1version integer no"
 231 .It "kern.procname      string  yes"
 232 .It "kern.safeboot      integer no"
 233 .It "kern.saved_ids     integer no"
 234 .It "kern.secure_kernel integer no"
 235 .It "kern.securelevel   integer yes"
 236 .It "kern.singleuser    integer no"
 237 .It "kern.sleeptime     struct  no"
 238 .It "kern.slide integer no"
 239 .It "kern.stack_depth_max       integer no"
 240 .It "kern.stack_size    integer no"
 241 .It "kern.sugid_coredump        integer yes"
 242 .It "kern.sugid_scripts integer yes"
 243 .It "kern.symfile       string  no"
 244 .It "kern.usrstack      integer no"
 245 .It "kern.usrstack64    integer no"
 246 .It "kern.uuid  string  no"
 247 .It "kern.version       string  no"
 248 .It "kern.waketime      struct  no"
 249 .It "machdep.cpu.address_bits.physical  integer no"
 250 .It "machdep.cpu.address_bits.virtual   integer no"
 251 .It "machdep.cpu.brand  integer no"
 252 .It "machdep.cpu.brand_string   string  no"
 253 .It "machdep.cpu.cache.L2_associativity integer no"
 254 .It "machdep.cpu.cache.linesize integer no"
 255 .It "machdep.cpu.cache.size     integer no"
 256 .It "machdep.cpu.core_count     integer no"
 257 .It "machdep.cpu.cores_per_package      integer no"
 258 .It "machdep.cpu.extfamily      integer no"
 259 .It "machdep.cpu.extfeature_bits        integer no"
 260 .It "machdep.cpu.extfeatures    string  no"
 261 .It "machdep.cpu.extmodel       integer no"
 262 .It "machdep.cpu.family integer no"
 263 .It "machdep.cpu.feature_bits   integer no"
 264 .It "machdep.cpu.features       string  no"
 265 .It "machdep.cpu.leaf7_feature_bits     integer no"
 266 .It "machdep.cpu.leaf7_features string  no"
 267 .It "machdep.cpu.logical_per_package    integer no"
 268 .It "machdep.cpu.max_basic      integer no"
 269 .It "machdep.cpu.max_ext        integer no"
 270 .It "machdep.cpu.microcode_version      integer no"
 271 .It "machdep.cpu.model  integer no"
 272 .It "machdep.cpu.processor_flag integer no"
 273 .It "machdep.cpu.signature      integer no"
 274 .It "machdep.cpu.stepping       integer no"
 275 .It "machdep.cpu.thread_count   integer no"
 276 .It "machdep.cpu.tlb.data.large integer no"
 277 .It "machdep.cpu.tlb.data.large_level1  integer no"
 278 .It "machdep.cpu.tlb.data.small integer no"
 279 .It "machdep.cpu.tlb.data.small_level1  integer no"
 280 .It "machdep.cpu.tlb.inst.large integer no"
 281 .It "machdep.cpu.tlb.inst.small integer no"
 282 .It "machdep.cpu.tlb.shared     integer no"
 283 .It "machdep.cpu.ucupdate       integer yes"
 284 .It "machdep.cpu.vendor string  no"
 285 .It "machdep.cpu.xsave.extended_state   integer no"
 286 .It "machdep.tsc.deep_idle_rebase       integer yes"
 287 .It "machdep.tsc.frequency      integer no"
 288 .It "machdep.tsc.nanotime.generation    integer no"
 289 .It "machdep.tsc.nanotime.shift integer no"
 290 .It "net.inet.ip.forwarding     integer yes"
 291 .It "net.inet.ip.portrange.first        integer yes"
 292 .It "net.inet.ip.portrange.hifirst      integer yes"
 293 .It "net.inet.ip.portrange.hilast       integer yes"
 294 .It "net.inet.ip.portrange.last integer yes"
 295 .It "net.inet.ip.portrange.lowfirst     integer yes"
 296 .It "net.inet.ip.portrange.lowlast      integer yes"
 297 .It "net.inet.ip.redirect       integer yes"
 298 .It "net.inet.ip.ttl    integer yes"
 299 .It "net.inet.udp.checksum      integer yes"
 300 .It "net.inet.udp.maxdgram      integer yes"
 301 .It "vm.loadavg struct  no"
 302 .It "vm.swapusage       struct  no"
 303 .It "user.bc_base_max   integer no"
 304 .It "user.bc_dim_max    integer no"
 305 .It "user.bc_scale_max  integer no"
 306 .It "user.bc_string_max integer no"
 307 .It "user.coll_weights_max      integer no"
 308 .It "user.cs_path       string  no"
 309 .It "user.expr_nest_max integer no"
 310 .It "user.line_max      integer no"
 311 .It "user.posix2_c_bind integer no"
 312 .It "user.posix2_c_dev  integer no"
 313 .It "user.posix2_char_term      integer no"
 314 .It "user.posix2_fort_dev       integer no"
 315 .It "user.posix2_fort_run       integer no"
 316 .It "user.posix2_localedef      integer no"
 317 .It "user.posix2_sw_dev integer no"
 318 .It "user.posix2_upe    integer no"
 319 .It "user.posix2_version        integer no"
 320 .It "user.re_dup_max    integer no"
 321 .It "user.stream_max    integer no"
 322 .It "user.tzname_max    integer no"
 323 .El
 324 .Sh FILES
 325 .Bl -tag -width ".In netinet/icmp_var.h" -compact
 326 .It In sys/sysctl.h
 327 definitions for top level identifiers, second level kernel and hardware
 328 identifiers, and user level identifiers
 329 .It In sys/socket.h
 330 definitions for second level network identifiers
 331 .It In sys/gmon.h
 332 definitions for third level profiling identifiers
 333 .It In vm/vm_param.h
 334 definitions for second level virtual memory identifiers
 335 .It In netinet/in.h
 336 definitions for third level Internet identifiers and
 337 fourth level IP identifiers
 338 .It In netinet/icmp_var.h
 339 definitions for fourth level ICMP identifiers
 340 .It In netinet/udp_var.h
 341 definitions for fourth level UDP identifiers
 342 .El
 343 .Sh EXAMPLES
 344 For example, to retrieve the maximum number of processes allowed
 345 in the system, one would use the following request:
 346 .Pp
 347 .Dl "sysctl kern.maxproc"
 348 .Pp
 349 To set the maximum number of processes allowed
 350 per uid to 1000, one would use the following request:
 351 .Pp
 352 .Dl "sysctl kern.maxprocperuid=1000"
 353 .Pp
 354 Information about the system clock rate may be obtained with:
 355 .Pp
 356 .Dl "sysctl kern.clockrate"
 357 .Pp
 358 Information about the load average history may be obtained with:
 359 .Pp
 360 .Dl "sysctl vm.loadavg"
 361 .Pp
 362 More variables than these exist, and the best and likely only place
 363 to search for their deeper meaning is undoubtedly the source where
 364 they are defined.
 365 .Sh COMPATIBILITY
 366 The
 367 .Fl w
 368 option has been deprecated and is silently ignored.
 369 .Sh SEE ALSO
 370 .Xr sysctl 3 ,
 371 .\" .Xr loader.conf 5 ,
 372 .Xr sysctl.conf 5
 373 .\" .Xr loader 8
 374 .Sh HISTORY
 375 A
 376 .Nm
 377 utility first appeared in
 378 .Bx 4.4 .
 379 .Pp
 380 In
 381 .Fx 2.2 ,
 382 .Nm
 383 was significantly remodeled.
 384 .\" .Sh BUGS
 385 .\" The
 386 .\" .Nm
 387 .\" utility presently exploits an undocumented interface to the kernel
 388 .\" sysctl facility to traverse the sysctl tree and to retrieve format
 389 .\" and name information.
 390 .\" This correct interface is being thought about for the time being.