1.\" $OpenBSD: options.4,v 1.243 2016/03/10 08:56:46 jmc 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: March 10 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 INSECURE 345Hardwires the kernel security level at \-1. 346This means that the system always runs in securelevel 0 mode, even when 347running multiuser. 348See 349.Xr init 8 350for details on the implications of this. 351The kernel secure level may be manipulated by the superuser by altering the 352.Em kern.securelevel 353sysctl variable. 354(It should be noted that the securelevel may only be lowered by a call from 355process ID 1, i.e., 356.Xr init 8 . ) 357See also 358.Xr sysctl 8 359and 360.Xr sysctl 3 . 361.It Cd option KMEMSTATS 362The kernel memory allocator, 363.Xr malloc 9 , 364will keep statistics on its performance if this option is enabled. 365Note that this option is silently turned on by the 366.Cm DEBUG 367option. 368.It Cd option MACOBIOVERBOSE 369Makes the boot process more verbose for OBIO peripherals on the 370.Va macppc 371architecture. 372.It Cd option MULTIPROCESSOR 373On those architectures that have it, this enables multiprocessor support. 374.It Cd option PCIVERBOSE 375Makes the boot process more verbose for PCI peripherals 376(vendor names and other information is printed, etc.). 377.It Cd option PCMCIAVERBOSE 378Makes the boot process more verbose for PCMCIA peripherals. 379.It Cd option USER_PCICONF 380Enables the user level access to the PCI bus configuration space 381through ioctls on the 382.Pa /dev/pci 383device. 384It's used by the 385.Xr Xorg 1 386server on some architectures. 387See 388.Xr pci 4 389for details. 390.It Cd option UVM_SWAP_ENCRYPT 391Enables kernel support for encrypting pages that are written out to 392swap storage. 393Swap encryption prevents sensitive data from remaining 394on the disk even after the operating system has been shut down. 395This option should be turned on if cryptographic filesystems are used. 396The sysctl variable 397.Em vm.swapencrypt.enable 398controls its behaviour. 399See 400.Xr sysctl 8 401and 402.Xr sysctl 3 403for details. 404.El 405.Sh NETWORKING OPTIONS 406.Bl -ohang 407.It Cd option ENCDEBUG 408This option enables debugging information to be conditionally logged 409in case IPSEC encounters errors. 410The option 411.Em IPSEC 412is required along with this option. 413Debug logging can be turned on/off through the use of the 414.Em net.inet.ip.encdebug 415sysctl variable. 416If 417.Em net.inet.ip.encdebug 418is 1, debug logging is on. 419See 420.Xr sysctl 8 421and 422.Xr sysctl 3 423for details. 424.It Cd option INET6 425Includes support for the IPv6 protocol stack. 426See 427.Xr inet6 4 428for details. 429.Em INET6 430enables multicast routing code as well. 431.It Cd option IPSEC 432This option enables IP security protocol support. 433See 434.Xr ipsec 4 435for more details. 436.It Cd option KEY 437Enables PFKEYv2 (RFC 2367) support. 438While not IP specific, this option is usually used in conjunction with option 439.Em IPSEC . 440.It Cd option MROUTING 441Includes support for IP multicast routers. 442Multicast routing is controlled by the 443.Xr mrouted 8 444daemon. 445.It Cd option ND6_DEBUG 446The option sets the default value of 447.Em net.inet6.icmp6.nd6_debug 448to 1, 449for debugging IPv6 neighbor discovery protocol handling. 450See 451.Xr sysctl 3 452for details. 453.It Cd option PIPEX 454Includes pipex in-kernel acceleration for PPPoE, L2TP or PPTP. 455See 456.Xr pipex 4 457for details. 458.It Cd option PPP_BSDCOMP 459Enables BSD compressor for PPP connections. 460.It Cd option PPP_DEFLATE 461For use in conjunction with PPP_BSDCOMP; provides an interface to zlib for PPP 462for deflate compression/decompression. 463.It Cd option SOCKET_SPLICE 464Enables zero-copy socket splicing in the kernel. 465See 466.Dv SO_SPLICE 467in 468.Xr setsockopt 2 469and 470.Xr sosplice 9 471for details. 472.It Cd option TCP_ECN 473Turns on Explicit Congestion Notification (RFC 3168). 474.Em ECN 475allows intermediate routers to use the Congestion Experienced 476codepoint in the IP header as an indication of congestion, and allows 477TCP to adjust the transmission rate using this signal. 478Both communication endpoints negotiate enabling 479.Em ECN 480functionality at the TCP connection establishment. 481.It Cd option TCP_FACK 482Turns on forward acknowledgements allowing a more precise estimate of 483outstanding data during the fast recovery phase by using 484.Em SACK 485information. 486This option can only be used together with 487.Em TCP_SACK . 488.It Cd option TCP_SACK 489Turns on selective acknowledgements. 490Additional information about 491segments already received can be transmitted back to the sender, 492thus indicating segments that have been lost and allowing for 493a swifter recovery. 494Both communication endpoints need to support 495.Em SACK . 496The fallback behaviour is NewReno fast recovery phase, which allows 497one lost segment to be recovered per round trip time. 498When more than one segment has been dropped per window, the transmission can 499continue without waiting for a retransmission timeout. 500.It Cd option TCP_SIGNATURE 501Turns on support for the TCP MD5 Signature option (RFC 2385). 502This is used by 503Internet backbone routers to provide per-packet authentication for the TCP 504packets used to communicate BGP routing information. 505You will also need a 506routing daemon that supports this option in order to actually use it. 507.El 508.Sh OPERATION RELATED OPTIONS 509.Bl -ohang -compact 510.It Cd option BUFPAGES= Ns Ar value 511.It Cd option NBUF= Ns Ar value 512These options set the number of pages available for the buffer cache. 513Their default value is a machine dependent value, often calculated as 514between 5% and 10% of total available RAM. 515.Pp 516.It Cd option DST= Ns Ar value 517If 518.Ar value 519is non-zero, indicates that the hardware realtime clock device 520is one hour ahead of the offset given in 521.Sq TIMEZONE , 522due to Daylight Saving Time (DST). 523If 524.Ar value 525is zero, the hardware realtime clock device is not in Daylight Saving Time. 526.Pp 527.It Cd option NKMEMPAGES= Ns Ar value 528.It Cd option NKMEMPAGES_MAX= Ns Ar value 529Size of kernel malloc area in PAGE_SIZE-sized logical pages. 530This area is covered by the kernel submap 531.Em kmem_map . 532The kernel attempts to auto-size this map based on the amount of 533physical memory in the system. 534Platform-specific code may place bounds on this computed size, 535which may be viewed with the 536.Xr sysctl 8 537variable 538.Em vm.nkmempages . 539See 540.Pa /usr/include/machine/param.h 541for the default upper bound. 542The related option 543.Sq NKMEMPAGES_MAX 544allows the bounds to be overridden in the kernel configuration file 545in the event the computed value is insufficient resulting in an 546.Dq out of space in kmem_map 547panic. 548.Pp 549.It Cd option \&"TIMEZONE= Ns Ar value Ns Cm \&" 550.Ar value 551indicates the time zone offset of the hardware realtime clock device, 552in minutes, 553from UTC. 554It is useful when the hardware realtime clock device is configured 555with local time, 556when dual-booting 557.Ox 558with other operating systems on a single machine. 559For instance, if the hardware realtime clock is set to Tokyo time, 560.Ar value 561should be 562.Li \&-540 563as Tokyo local time is 9 hours ahead of UTC. 564Double quotes are needed when specifying a negative 565.Ar value . 566.El 567.Sh SCSI SUBSYSTEM OPTIONS 568.Bl -ohang 569.It Cd option SCSI_DELAY= Ns Ar value 570Delay for 571.Ar value 572seconds before starting to probe the first SCSI bus. 573This can be used if a SCSI device needs extra time to get ready. 574.It Cd option SCSIDEBUG 575Enable printing of SCSI subsystem debugging info to the console. 576Each of 577.Em SCSIDEBUG_LEVEL , 578.Em SCSIDEBUG_BUSES , 579.Em SCSIDEBUG_TARGETS 580and 581.Em SCSIDEBUG_LUNS 582must have non-zero values for any debugging info to be printed. 583Only 584.Em SCSIDEBUG_LEVEL 585has a default value (SDEV_DB1 | SDEV_DB2) that is non-zero. 586.It Cd option SCSIDEBUG_BUSES= Ns Ar value 587Define which SCSI buses will print debug info. 588Each bit enables debugging info for the corresponding bus. 589e.g. a value of 0x1 enables debug info for bus 0. 590.It Cd option SCSIDEBUG_LEVEL= Ns Ar value 591Define which of the four levels of debugging info are printed. 592Each bit enables a level, and multiple levels are specified by setting multiple 593bits. 594.Bd -literal -offset indent 5950x0010 (SDEV_DB1) SCSI commands, errors, and data 5960x0020 (SDEV_DB2) routine flow 5970x0040 (SDEV_DB3) routine internals 5980x0080 (SDEV_DB4) miscellaneous addition debugging 599.Ed 600.Pp 601If 602.Em SCSIDEBUG_LEVEL 603is undefined, a value of 0x0030 (SDEV_DB1|SDEV_DB2) is used. 604.It Cd option SCSIDEBUG_LUNS= Ns Ar value 605Define which SCSI luns will print debug info. 606Each bit enables debugging info for the corresponding lun. 607.It Cd option SCSIDEBUG_TARGETS= Ns Ar value 608Define which SCSI targets will print debug info. 609Each bit enables debugging info for the corresponding target. 610.It Cd option SCSITERSE 611Terser SCSI error messages. 612This omits the table for decoding ASC/ASCQ info, saving about 30KB. 613.El 614.Sh SYSTEM V IPC OPTIONS 615.Bl -ohang 616.It Cd option SEMMNI= Ns Ar value 617Number of semaphore identifiers (also called semaphore handles 618and semaphore sets) available in the system. 619Default value is 10. 620The kernel allocates memory for the control structures at startup, 621so arbitrarily large values should be avoided. 622.It Cd option SEMMNS= Ns Ar value 623Maximum number of semaphores in all sets in the system. 624Default value is 60. 625.It Cd option SEMMNU= Ns Ar value 626Maximum number of semaphore undo structures in the system. 627Default value is 30. 628.It Cd option SEMUME= Ns Ar value 629Maximum number of per-process undo operation entries in the 630system. 631Semaphore undo operations are invoked by the kernel when 632.Xr semop 2 633is called with the SEM_UNDO flag and the process holding 634the semaphores terminates unexpectedly. 635Default value is 10. 636.It Cd option SHMMAXPGS= Ns Ar value 637Sets the maximum number of 638.At V 639style shared memory pages that are available through the 640.Xr shmget 2 641system call. 642Default value is 1024 on most architectures. 643See 644.Pa /usr/include/machine/vmparam.h 645for the default. 646.It Cd option SYSVMSG 647Includes support for 648.At V 649style message queues. 650See 651.Xr msgctl 2 , 652.Xr msgget 2 , 653.Xr msgrcv 2 , 654.Xr msgsnd 2 . 655.It Cd option SYSVSEM 656Includes support for 657.At V 658style semaphores. 659See 660.Xr semctl 2 , 661.Xr semget 2 , 662.Xr semop 2 . 663.It Cd option SYSVSHM 664Includes support for 665.At V 666style shared memory. 667See 668.Xr shmat 2 , 669.Xr shmctl 2 , 670.Xr shmdt 2 , 671.Xr shmget 2 . 672.El 673.Sh SEE ALSO 674.Xr intro 4 , 675.Xr files.conf 5 , 676.Xr config 8 , 677.Xr sysctl 8 678.Sh HISTORY 679The 680.Nm 681man page first appeared in 682.Ox 2.3 . 683