1.\" $OpenBSD: options.4,v 1.244 2016/09/18 14:28:04 deraadt Exp $ 2.\" $NetBSD: options.4,v 1.21 1997/06/25 03:13:00 thorpej Exp $ 3.\" 4.\" Copyright (c) 1998 Theo de Raadt 5.\" Copyright (c) 1998 Todd Miller 6.\" Copyright (c) 1998 Gene Skonicki 7.\" Copyright (c) 1996 8.\" Perry E. Metzger. All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgment: 20.\" This product includes software developed for the NetBSD Project 21.\" by Perry E. Metzger. 22.\" 4. The name of the author may not be used to endorse or promote products 23.\" derived from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 26.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 27.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 28.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 29.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 30.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 31.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 32.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 33.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 34.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 35.\" 36.\" 37.Dd $Mdocdate: September 18 2016 $ 38.Dt OPTIONS 4 39.Os 40.Sh NAME 41.Nm options 42.Nd kernel configuration options 43.Sh SYNOPSIS 44.Cd option ... 45.Sh DESCRIPTION 46This manual page describes a number of miscellaneous kernel 47configuration options that may be specified in a kernel config file. 48See 49.Xr config 8 50for information on how to configure and build kernels. 51.Em Note: 52options are passed to the compile process as 53.Fl D 54flags to the C compiler. 55.Sh DEBUGGING OPTIONS 56.Bl -ohang 57.It Cd makeoptions DEBUG="-g" 58The 59.Fl g 60flag causes 61.Pa bsd.gdb 62to be built in addition to 63.Pa bsd . 64.Pa bsd.gdb 65is useful for debugging kernels and their crash dumps with gdb. 66A crash dump can be debugged by starting 67.Xr gdb 1 68with the kernel name 69.Pf ( Pa bsd.gdb ) 70as an argument (no core file) and then use the 71.Xr gdb 1 72command 73.Dq target kvm COREFILE . 74.It Cd makeoptions PROF="-pg" 75The 76.Fl pg 77flag causes the kernel to be compiled with support for profiling. 78The 79.Cm option GPROF 80is required for the kernel compile to succeed. 81.It Cd option ACCOUNTING 82Adds support for the 83.Xr acct 2 84system call. 85.It Cd option DDB 86Compiles in a kernel debugger for diagnosing kernel problems. 87See 88.Xr ddb 4 89for details. 90.It Cd option DDB_SAFE_CONSOLE 91Allows a break into the kernel debugger during boot. 92Useful when debugging problems that can cause 93.Xr init 8 94to fail. 95.It Cd option DDB_STRUCT 96Compiles in symbolic information about the various data structures used by the 97kernel, for use within the kernel debugger. 98This option is currently not supported on alpha and m88k based platforms. 99.It Cd option DEBUG 100Turns on miscellaneous kernel debugging. 101Since options are turned into preprocessor defines (see above), 102.Cm option DEBUG 103is equivalent to doing a 104.Em #define DEBUG 105throughout the kernel. 106Much of the kernel has 107.Em #ifdef DEBUG 108conditional debugging code. 109Note that many parts of the kernel (typically device drivers) include their own 110.Em #ifdef XXX_DEBUG 111conditionals instead. 112This option also turns on certain other options, notably 113.Cm option KMEMSTATS . 114.It Cd option DIAGNOSTIC 115Adds code to the kernel that does internal consistency checks. 116This code will cause the kernel to panic if corruption of internal data 117structures is detected. 118.It Cd option GPROF 119Adds code to the kernel for kernel profiling with 120.Xr kgmon 8 . 121.It Cd option KGDB 122Compiles in a remote kernel debugger stub for diagnosing kernel problems 123using the 124.Dq remote target 125feature of gdb. 126See 127.Xr kgdb 7 128for details. 129.Em Note: 130not available on all architectures. 131.It Cd option KTRACE 132Adds hooks for the system call tracing facility, which allows users to 133watch the system call invocation behavior of processes. 134See 135.Xr ktrace 1 136for details. 137.It Cd option NO_PROPOLICE 138Do not compile the kernel with the ProPolice stack protection. 139See 140.Xr gcc-local 1 141for more information about ProPolice. 142.It Cd option PTRACE 143Adds hooks for the process tracing facility, allowing a process to 144control and observe another process. 145See 146.Xr ptrace 2 147for details. 148.It Cd option SMALL_KERNEL 149Removes some features and some optimizations from the kernel to reduce the 150size of the resulting kernel binary. 151This option is used on some installation media and should not be used 152for general purpose kernels. 153.It Cd option VFSLCKDEBUG 154Turns on debugging for the Virtual File System interface. 155See 156.Xr vfs 9 157for details. 158.El 159.Sh FILE SYSTEMS 160.Bl -ohang 161.It Cd option CD9660 162Includes code for the ISO 9660 + Rock Ridge file system, which is the 163standard file system used on many CD-ROMs. 164It also supports Joliet extensions. 165See 166.Xr mount_cd9660 8 167for details. 168.It Cd option EXT2FS 169Includes code implementing the Second Extended File System 170.Em ( EXT2FS ) , 171commonly used on the Linux operating system. 172This option is provided here for compatibility. 173Some specific features of 174.Em EXT2FS 175like the "behavior on errors" are not implemented. 176This file system 177can't be used with 178.Li uid_t 179or 180.Li gid_t 181values greater than 65535. 182Also, the filesystem will not function correctly on architectures with 183differing byte-orders. 184That is, a big-endian machine will not be able to read an 185ext2fs filesystem created on an i386 or other little-endian machine. 186See 187.Xr mount_ext2fs 8 188for details. 189.It Cd option FFS 190Includes code implementing the Berkeley Fast File System 191.Em ( FFS ) . 192Most machines need this if they are not running diskless. 193.It Cd option FFS2 194Includes code implementing the enhanced Fast File System 195.Em ( FFS2 ) . 196.It Cd option MFS 197Include the memory file system 198.Em ( MFS ) . 199This file system stores files in swappable memory, and produces 200notable performance improvements when it is used as the file store 201for 202.Pa /tmp 203or similar mount points. 204See 205.Xr mount_mfs 8 206for details. 207.It Cd option MSDOSFS 208Includes support for the MS-DOS FAT file system. 209The kernel also implements the Windows 95 210extensions which permit the use of longer, mixed-case file names. 211See 212.Xr mount_msdos 8 213and 214.Xr fsck_msdos 8 215for details. 216.It Cd option NFSCLIENT 217Include the client side of the 218.Em NFS 219(Network File System) remote file sharing protocol. 220Although the bulk of the code implementing 221.Em NFS 222is kernel based, several user level daemons are needed for it to work. 223See 224.Xr mount_nfs 8 225for details on NFS. 226.It Cd option NTFS 227Includes support for reading NTFS file systems. 228See 229.Xr mount_ntfs 8 230for details. 231.It Cd option UDF 232Includes code for the UDF file systems typically found on DVD discs. 233See 234.Xr mount_udf 8 235for details. 236.It Cd option TMPFS 237Includes code for the TMPFS efficient memory file system. 238See 239.Xr mount_tmpfs 8 240for details. 241.El 242.Sh FILE SYSTEM OPTIONS 243.Bl -ohang 244.It Cd option BUFCACHEPERCENT= Ns Ar integer 245Percentage of RAM to use as a file system buffer. 246It defaults to 20. 247.It Cd option EXT2FS_SYSTEM_FLAGS 248This option changes the behavior of the APPEND and IMMUTABLE flags 249for a file on an 250.Em EXT2FS 251filesystem. 252Without this option, the superuser or owner of the file can set and clear them. 253With this option, only the superuser can set them, and they can't be cleared 254if the securelevel is greater than 0. 255See also 256.Xr chflags 1 . 257.It Cd option FFS_SOFTUPDATES 258Enables a scheme that uses partial ordering of buffer cache operations 259to allow metadata updates in FFS to happen asynchronously, increasing write 260performance significantly. 261Normally, the FFS filesystem writes metadata updates synchronously which exacts 262a performance penalty in favor of filesystem integrity. 263With soft updates, the performance of asynchronous writes is gained while 264retaining the safety of synchronous metadata updates. 265.Pp 266Soft updates must be enabled on a per-filesystem basis. 267See 268.Xr mount 8 269for details. 270.Pp 271Processors with a small kernel address space, such as the sun4 and sun4c, do 272not have enough kernel memory to support soft updates. 273Attempts to use this option with these CPUs will cause a kernel hang or panic 274after a short period of use as the kernel will quickly run out of memory. 275This is not related to the amount of physical memory present in the machine -- 276it is a limitation of the CPU architecture itself. 277.It Cd option FIFO 278Adds support for 279.At V 280style FIFOs (i.e., 281.Dq named pipes ) . 282This option is recommended in almost all cases as many programs use these. 283.It Cd option NFSSERVER 284Include the server side of the 285.Em NFS 286(Network File System) remote file sharing protocol. 287Although the bulk of the code implementing 288.Em NFS 289is kernel based, several user level daemons are needed for it to 290work. 291See 292.Xr mountd 8 293and 294.Xr nfsd 8 295for details. 296.It Cd option QUOTA 297Enables kernel support for file system quotas. 298See 299.Xr quotaon 8 , 300.Xr edquota 8 , 301.Xr repquota 8 , 302and 303.Xr quota 1 304for details. 305Note that quotas only work on 306.Dq ffs 307file systems, although 308.Xr rpc.rquotad 8 309permits them to be accessed over 310.Em NFS . 311.It Cd option UFS_DIRHASH 312This option enables using an in memory hash table to speed lookups 313in large directories. 314.El 315.Sh MISCELLANEOUS OPTIONS 316.Bl -ohang 317.It Cd option APERTURE 318Provide in-kernel support for controlling VGA framebuffer mapping 319and PCI configuration registers by user-processes 320(such as an X Window System server). 321This option is supported on the 322.Va alpha , 323.Va amd64 , 324.Va i386 , 325.Va macppc , 326and 327.Va sparc64 328architectures. 329.It Cd option BOOT_CONFIG 330Adds support for the 331.Fl c 332boot option (User Kernel Config). 333Allows modification of kernel settings (e.g., device parameters) before 334booting the system. 335.It Cd option CRYPTO 336Enables support for the kernel cryptographic framework. 337See 338.Xr crypto 9 339for details. 340While not IP specific, this option is usually used in conjunction with option 341.Em IPSEC . 342.It Cd option EISAVERBOSE 343Makes the boot process more verbose for EISA peripherals. 344.It Cd option KMEMSTATS 345The kernel memory allocator, 346.Xr malloc 9 , 347will keep statistics on its performance if this option is enabled. 348Note that this option is silently turned on by the 349.Cm DEBUG 350option. 351.It Cd option MACOBIOVERBOSE 352Makes the boot process more verbose for OBIO peripherals on the 353.Va macppc 354architecture. 355.It Cd option MULTIPROCESSOR 356On those architectures that have it, this enables multiprocessor support. 357.It Cd option PCIVERBOSE 358Makes the boot process more verbose for PCI peripherals 359(vendor names and other information is printed, etc.). 360.It Cd option PCMCIAVERBOSE 361Makes the boot process more verbose for PCMCIA peripherals. 362.It Cd option USER_PCICONF 363Enables the user level access to the PCI bus configuration space 364through ioctls on the 365.Pa /dev/pci 366device. 367It's used by the 368.Xr Xorg 1 369server on some architectures. 370See 371.Xr pci 4 372for details. 373.It Cd option UVM_SWAP_ENCRYPT 374Enables kernel support for encrypting pages that are written out to 375swap storage. 376Swap encryption prevents sensitive data from remaining 377on the disk even after the operating system has been shut down. 378This option should be turned on if cryptographic filesystems are used. 379The sysctl variable 380.Em vm.swapencrypt.enable 381controls its behaviour. 382See 383.Xr sysctl 8 384and 385.Xr sysctl 3 386for details. 387.El 388.Sh NETWORKING OPTIONS 389.Bl -ohang 390.It Cd option ENCDEBUG 391This option enables debugging information to be conditionally logged 392in case IPSEC encounters errors. 393The option 394.Em IPSEC 395is required along with this option. 396Debug logging can be turned on/off through the use of the 397.Em net.inet.ip.encdebug 398sysctl variable. 399If 400.Em net.inet.ip.encdebug 401is 1, debug logging is on. 402See 403.Xr sysctl 8 404and 405.Xr sysctl 3 406for details. 407.It Cd option INET6 408Includes support for the IPv6 protocol stack. 409See 410.Xr inet6 4 411for details. 412.Em INET6 413enables multicast routing code as well. 414.It Cd option IPSEC 415This option enables IP security protocol support. 416See 417.Xr ipsec 4 418for more details. 419.It Cd option KEY 420Enables PFKEYv2 (RFC 2367) support. 421While not IP specific, this option is usually used in conjunction with option 422.Em IPSEC . 423.It Cd option MROUTING 424Includes support for IP multicast routers. 425Multicast routing is controlled by the 426.Xr mrouted 8 427daemon. 428.It Cd option ND6_DEBUG 429The option sets the default value of 430.Em net.inet6.icmp6.nd6_debug 431to 1, 432for debugging IPv6 neighbor discovery protocol handling. 433See 434.Xr sysctl 3 435for details. 436.It Cd option PIPEX 437Includes pipex in-kernel acceleration for PPPoE, L2TP or PPTP. 438See 439.Xr pipex 4 440for details. 441.It Cd option PPP_BSDCOMP 442Enables BSD compressor for PPP connections. 443.It Cd option PPP_DEFLATE 444For use in conjunction with PPP_BSDCOMP; provides an interface to zlib for PPP 445for deflate compression/decompression. 446.It Cd option SOCKET_SPLICE 447Enables zero-copy socket splicing in the kernel. 448See 449.Dv SO_SPLICE 450in 451.Xr setsockopt 2 452and 453.Xr sosplice 9 454for details. 455.It Cd option TCP_ECN 456Turns on Explicit Congestion Notification (RFC 3168). 457.Em ECN 458allows intermediate routers to use the Congestion Experienced 459codepoint in the IP header as an indication of congestion, and allows 460TCP to adjust the transmission rate using this signal. 461Both communication endpoints negotiate enabling 462.Em ECN 463functionality at the TCP connection establishment. 464.It Cd option TCP_FACK 465Turns on forward acknowledgements allowing a more precise estimate of 466outstanding data during the fast recovery phase by using 467.Em SACK 468information. 469This option can only be used together with 470.Em TCP_SACK . 471.It Cd option TCP_SACK 472Turns on selective acknowledgements. 473Additional information about 474segments already received can be transmitted back to the sender, 475thus indicating segments that have been lost and allowing for 476a swifter recovery. 477Both communication endpoints need to support 478.Em SACK . 479The fallback behaviour is NewReno fast recovery phase, which allows 480one lost segment to be recovered per round trip time. 481When more than one segment has been dropped per window, the transmission can 482continue without waiting for a retransmission timeout. 483.It Cd option TCP_SIGNATURE 484Turns on support for the TCP MD5 Signature option (RFC 2385). 485This is used by 486Internet backbone routers to provide per-packet authentication for the TCP 487packets used to communicate BGP routing information. 488You will also need a 489routing daemon that supports this option in order to actually use it. 490.El 491.Sh OPERATION RELATED OPTIONS 492.Bl -ohang -compact 493.It Cd option BUFPAGES= Ns Ar value 494.It Cd option NBUF= Ns Ar value 495These options set the number of pages available for the buffer cache. 496Their default value is a machine dependent value, often calculated as 497between 5% and 10% of total available RAM. 498.Pp 499.It Cd option DST= Ns Ar value 500If 501.Ar value 502is non-zero, indicates that the hardware realtime clock device 503is one hour ahead of the offset given in 504.Sq TIMEZONE , 505due to Daylight Saving Time (DST). 506If 507.Ar value 508is zero, the hardware realtime clock device is not in Daylight Saving Time. 509.Pp 510.It Cd option NKMEMPAGES= Ns Ar value 511.It Cd option NKMEMPAGES_MAX= Ns Ar value 512Size of kernel malloc area in PAGE_SIZE-sized logical pages. 513This area is covered by the kernel submap 514.Em kmem_map . 515The kernel attempts to auto-size this map based on the amount of 516physical memory in the system. 517Platform-specific code may place bounds on this computed size, 518which may be viewed with the 519.Xr sysctl 8 520variable 521.Em vm.nkmempages . 522See 523.Pa /usr/include/machine/param.h 524for the default upper bound. 525The related option 526.Sq NKMEMPAGES_MAX 527allows the bounds to be overridden in the kernel configuration file 528in the event the computed value is insufficient resulting in an 529.Dq out of space in kmem_map 530panic. 531.Pp 532.It Cd option \&"TIMEZONE= Ns Ar value Ns Cm \&" 533.Ar value 534indicates the time zone offset of the hardware realtime clock device, 535in minutes, 536from UTC. 537It is useful when the hardware realtime clock device is configured 538with local time, 539when dual-booting 540.Ox 541with other operating systems on a single machine. 542For instance, if the hardware realtime clock is set to Tokyo time, 543.Ar value 544should be 545.Li \&-540 546as Tokyo local time is 9 hours ahead of UTC. 547Double quotes are needed when specifying a negative 548.Ar value . 549.El 550.Sh SCSI SUBSYSTEM OPTIONS 551.Bl -ohang 552.It Cd option SCSI_DELAY= Ns Ar value 553Delay for 554.Ar value 555seconds before starting to probe the first SCSI bus. 556This can be used if a SCSI device needs extra time to get ready. 557.It Cd option SCSIDEBUG 558Enable printing of SCSI subsystem debugging info to the console. 559Each of 560.Em SCSIDEBUG_LEVEL , 561.Em SCSIDEBUG_BUSES , 562.Em SCSIDEBUG_TARGETS 563and 564.Em SCSIDEBUG_LUNS 565must have non-zero values for any debugging info to be printed. 566Only 567.Em SCSIDEBUG_LEVEL 568has a default value (SDEV_DB1 | SDEV_DB2) that is non-zero. 569.It Cd option SCSIDEBUG_BUSES= Ns Ar value 570Define which SCSI buses will print debug info. 571Each bit enables debugging info for the corresponding bus. 572e.g. a value of 0x1 enables debug info for bus 0. 573.It Cd option SCSIDEBUG_LEVEL= Ns Ar value 574Define which of the four levels of debugging info are printed. 575Each bit enables a level, and multiple levels are specified by setting multiple 576bits. 577.Bd -literal -offset indent 5780x0010 (SDEV_DB1) SCSI commands, errors, and data 5790x0020 (SDEV_DB2) routine flow 5800x0040 (SDEV_DB3) routine internals 5810x0080 (SDEV_DB4) miscellaneous addition debugging 582.Ed 583.Pp 584If 585.Em SCSIDEBUG_LEVEL 586is undefined, a value of 0x0030 (SDEV_DB1|SDEV_DB2) is used. 587.It Cd option SCSIDEBUG_LUNS= Ns Ar value 588Define which SCSI luns will print debug info. 589Each bit enables debugging info for the corresponding lun. 590.It Cd option SCSIDEBUG_TARGETS= Ns Ar value 591Define which SCSI targets will print debug info. 592Each bit enables debugging info for the corresponding target. 593.It Cd option SCSITERSE 594Terser SCSI error messages. 595This omits the table for decoding ASC/ASCQ info, saving about 30KB. 596.El 597.Sh SYSTEM V IPC OPTIONS 598.Bl -ohang 599.It Cd option SEMMNI= Ns Ar value 600Number of semaphore identifiers (also called semaphore handles 601and semaphore sets) available in the system. 602Default value is 10. 603The kernel allocates memory for the control structures at startup, 604so arbitrarily large values should be avoided. 605.It Cd option SEMMNS= Ns Ar value 606Maximum number of semaphores in all sets in the system. 607Default value is 60. 608.It Cd option SEMMNU= Ns Ar value 609Maximum number of semaphore undo structures in the system. 610Default value is 30. 611.It Cd option SEMUME= Ns Ar value 612Maximum number of per-process undo operation entries in the 613system. 614Semaphore undo operations are invoked by the kernel when 615.Xr semop 2 616is called with the SEM_UNDO flag and the process holding 617the semaphores terminates unexpectedly. 618Default value is 10. 619.It Cd option SHMMAXPGS= Ns Ar value 620Sets the maximum number of 621.At V 622style shared memory pages that are available through the 623.Xr shmget 2 624system call. 625Default value is 1024 on most architectures. 626See 627.Pa /usr/include/machine/vmparam.h 628for the default. 629.It Cd option SYSVMSG 630Includes support for 631.At V 632style message queues. 633See 634.Xr msgctl 2 , 635.Xr msgget 2 , 636.Xr msgrcv 2 , 637.Xr msgsnd 2 . 638.It Cd option SYSVSEM 639Includes support for 640.At V 641style semaphores. 642See 643.Xr semctl 2 , 644.Xr semget 2 , 645.Xr semop 2 . 646.It Cd option SYSVSHM 647Includes support for 648.At V 649style shared memory. 650See 651.Xr shmat 2 , 652.Xr shmctl 2 , 653.Xr shmdt 2 , 654.Xr shmget 2 . 655.El 656.Sh SEE ALSO 657.Xr intro 4 , 658.Xr files.conf 5 , 659.Xr config 8 , 660.Xr sysctl 8 661.Sh HISTORY 662The 663.Nm 664man page first appeared in 665.Ox 2.3 . 666