1.\" $OpenBSD: options.4,v 1.264 2019/04/21 15:33:39 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: April 21 2019 $ 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="" 58Do not build the debug kernel 59.Pa bsd.gdb . 60Normally, 61.Pa bsd.gdb 62is built 63(in addition to the regular 64.Pa bsd 65kernel) 66and is used for debugging kernels and their crash dumps with 67.Xr gdb 1 . 68A crash dump can be debugged by starting gdb with 69.Pa bsd.gdb 70as an argument (no core file) and then using the gdb command 71.Dq target kvm COREFILE . 72.It Cd makeoptions PROF="-pg" 73The 74.Fl pg 75flag causes the kernel to be compiled with support for profiling. 76The 77.Cm option GPROF 78is required for the kernel compile to succeed. 79.It Cd option ACCOUNTING 80Adds support for the 81.Xr acct 2 82system call. 83.It Cd option DDB 84Compiles in a kernel debugger for diagnosing kernel problems. 85See 86.Xr ddb 4 . 87.It Cd option DDB_SAFE_CONSOLE 88Allows a break into the kernel debugger during boot. 89Useful when debugging problems that can cause 90.Xr init 8 91to fail. 92.It Cd option DEBUG 93Turns on miscellaneous kernel debugging. 94Since options are turned into preprocessor defines (see above), 95.Cm option DEBUG 96is equivalent to doing a 97.Em #define DEBUG 98throughout the kernel. 99Much of the kernel has 100.Em #ifdef DEBUG 101conditional debugging code. 102Note that many parts of the kernel (typically device drivers) include their own 103.Em #ifdef XXX_DEBUG 104conditionals instead. 105.It Cd option DIAGNOSTIC 106Adds code to the kernel that does internal consistency checks. 107This code will cause the kernel to panic if corruption of internal data 108structures is detected. 109.It Cd option GPROF 110Adds code to the kernel for kernel profiling with 111.Xr kgmon 8 . 112.It Cd option KTRACE 113Adds hooks for the system call tracing facility, which allows users to 114watch the system call invocation behavior of processes. 115See 116.Xr ktrace 1 . 117.It Cd option KUBSAN 118Detect undefined behavior in the kernel. 119See 120.Xr kubsan 4 . 121.It Cd option NO_PROPOLICE 122Do not compile the kernel with the ProPolice stack protection. 123See 124.Xr gcc-local 1 125for more information about ProPolice. 126.It Cd option PTRACE 127Adds hooks for the process tracing facility, allowing a process to 128control and observe another process. 129See 130.Xr ptrace 2 . 131.It Cd option SMALL_KERNEL 132Removes some features and some optimizations from the kernel to reduce the 133size of the resulting kernel binary. 134This option is used on some installation media and should not be used 135for general purpose kernels. 136.It Cd option VFSLCKDEBUG 137Turns on debugging for the Virtual File System interface. 138See 139.Xr vfs 9 . 140.It Cd option WITNESS 141Compiles in a lock checker for detecting lock order violations in the kernel. 142See 143.Xr witness 4 . 144.It Cd option WITNESS_COUNT= Ns Ar integer 145Maximum number of lock types that are tracked by 146.Xr witness 4 . 147It defaults to 1536. 148.It Cd option WITNESS_LOCKTRACE 149Enable 150.Xr witness 4 151lock stack trace saving at boot. 152The feature is disabled by default and has to be enabled by setting the 153.Va kern.witness.locktrace 154.Xr sysctl 8 155variable. 156.It Cd option WITNESS_WATCH 157Enable 158.Xr witness 4 159at boot. 160By default, the subsystem is disabled and has to be enabled at runtime 161by raising the 162.Va kern.witness.watch 163.Xr sysctl 8 164variable. 165.El 166.Sh FILE SYSTEMS 167.Bl -ohang 168.It Cd option CD9660 169Includes code for the ISO 9660 + Rock Ridge file system, which is the 170standard file system used on many CD-ROMs. 171It also supports Joliet extensions. 172See 173.Xr mount_cd9660 8 . 174.It Cd option EXT2FS 175Includes code implementing the Second Extended File System 176.Em ( EXT2FS ) , 177commonly used on the Linux operating system. 178This option is provided here for compatibility. 179Some specific features of 180.Em EXT2FS 181like the "behavior on errors" are not implemented. 182This file system 183can't be used with 184.Li uid_t 185or 186.Li gid_t 187values greater than 65535. 188Also, the filesystem will not function correctly on architectures with 189differing byte-orders. 190That is, a big-endian machine will not be able to read an 191ext2fs filesystem created on an i386 or other little-endian machine. 192See 193.Xr mount_ext2fs 8 . 194.It Cd option FFS 195Includes code implementing the Berkeley Fast File System 196.Em ( FFS ) . 197Most machines need this if they are not running diskless. 198.It Cd option FFS2 199Includes code implementing the enhanced Fast File System 200.Em ( FFS2 ) . 201.It Cd option MFS 202Include the memory file system 203.Em ( MFS ) . 204This file system stores files in swappable memory, and produces 205notable performance improvements when it is used as the file store 206for 207.Pa /tmp 208or similar mount points. 209See 210.Xr mount_mfs 8 . 211.It Cd option MSDOSFS 212Includes support for the MS-DOS FAT file system. 213The kernel also implements the Windows 95 214extensions which permit the use of longer, mixed-case file names. 215See 216.Xr mount_msdos 8 217and 218.Xr fsck_msdos 8 . 219.It Cd option NFSCLIENT 220Include the client side of the 221.Em NFS 222(Network File System) remote file sharing protocol. 223Although the bulk of the code implementing 224.Em NFS 225is kernel based, several user level daemons are needed for it to work. 226See 227.Xr mount_nfs 8 228for details on NFS. 229.It Cd option NTFS 230Includes support for reading NTFS file systems. 231See 232.Xr mount_ntfs 8 . 233.It Cd option UDF 234Includes code for the UDF file systems typically found on DVD discs. 235See 236.Xr mount_udf 8 . 237.It Cd option TMPFS 238Includes code for the TMPFS efficient memory file system. 239See 240.Xr mount_tmpfs 8 . 241.El 242.Sh FILE SYSTEM OPTIONS 243.Bl -ohang 244.It Cd option BUFCACHEPERCENT= Ns Ar integer 245Percentage of DMA-reachable RAM to use as a file system buffer. 246It defaults to 80. 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 . 269.Pp 270Processors with a small kernel address space, such as the sun4 and sun4c, do 271not have enough kernel memory to support soft updates. 272Attempts to use this option with these CPUs will cause a kernel hang or panic 273after a short period of use as the kernel will quickly run out of memory. 274This is not related to the amount of physical memory present in the 275machine \(em it is a limitation of the CPU architecture itself. 276.It Cd option FIFO 277Adds support for 278.At V 279style FIFOs (i.e., 280.Dq named pipes ) . 281This option is recommended in almost all cases as many programs use these. 282.It Cd option NFSSERVER 283Include the server side of the 284.Em NFS 285(Network File System) remote file sharing protocol. 286Although the bulk of the code implementing 287.Em NFS 288is kernel based, several user level daemons are needed for it to 289work. 290See 291.Xr mountd 8 292and 293.Xr nfsd 8 . 294.It Cd option QUOTA 295Enables kernel support for file system quotas. 296See 297.Xr quotaon 8 , 298.Xr edquota 8 , 299.Xr repquota 8 , 300and 301.Xr quota 1 . 302Note that quotas only work on 303.Dq ffs 304file systems, although 305.Xr rpc.rquotad 8 306permits them to be accessed over 307.Em NFS . 308.It Cd option UFS_DIRHASH 309This option enables using an in memory hash table to speed lookups 310in large directories. 311.El 312.Sh MISCELLANEOUS OPTIONS 313.Bl -ohang 314.It Cd option APERTURE 315Provide in-kernel support for controlling VGA framebuffer mapping 316and PCI configuration registers by user-processes 317(such as an X Window System server). 318See 319.Xr xf86 4 . 320This option is supported on the 321.Va alpha , 322.Va amd64 , 323.Va i386 , 324.Va macppc , 325and 326.Va sparc64 327architectures. 328.It Cd option BOOT_CONFIG 329Adds support for the 330.Fl c 331boot option (User Kernel Config). 332Allows modification of kernel settings (e.g., device parameters) before 333booting the system. 334See 335.Xr boot_config 8 . 336.It Cd option CRYPTO 337Enables support for the kernel cryptographic framework. 338See 339.Xr crypto 9 . 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. 344See 345.Xr eisa 4 . 346.It Cd option KMEMSTATS 347The kernel memory allocator, 348.Xr malloc 9 , 349will keep statistics on its performance if this option is enabled. 350.It Cd option MULTIPROCESSOR 351On those architectures that have it, this enables multiprocessor support. 352.It Cd option PCIVERBOSE 353Makes the boot process more verbose for PCI peripherals 354(vendor names and other information is printed, etc.). 355See 356.Xr pci 4 . 357.It Cd option PCMCIAVERBOSE 358Makes the boot process more verbose for PCMCIA peripherals. 359See 360.Xr pcmcia 4 . 361.It Cd option USER_PCICONF 362Enables the user level access to the PCI bus configuration space 363through ioctls on the 364.Pa /dev/pci 365device. 366It's used by 367.Xr Xorg 1 368and 369.Xr pcidump 8 . 370See 371.Xr pci 4 . 372.It Cd option UVM_SWAP_ENCRYPT 373Enables kernel support for encrypting pages that are written out to 374swap storage. 375Swap encryption prevents sensitive data from remaining 376on the disk even after the operating system has been shut down. 377This option should be turned on if cryptographic filesystems are used. 378The sysctl variable 379.Em vm.swapencrypt.enable 380controls its behaviour. 381See 382.Xr sysctl 8 383and 384.Xr sysctl 2 . 385.El 386.Sh NETWORKING OPTIONS 387.Bl -ohang 388.It Cd option ENCDEBUG 389This option permits the conditional logging of IPsec debugging information, 390and requires the 391.Em IPSEC 392option. 393Debug logging can be turned on/off through the use of the 394.Em net.inet.ip.encdebug 395sysctl variable. 396If 397.Em net.inet.ip.encdebug 398is 1, debug logging is on. 399See 400.Xr sysctl 8 401and 402.Xr sysctl 2 . 403.It Cd option INET6 404Includes support for the IPv6 protocol stack. 405See 406.Xr inet6 4 . 407.Em INET6 408enables multicast routing code as well. 409.It Cd option IPSEC 410This option enables IP security protocol support. 411See 412.Xr ipsec 4 413for more details. 414.It Cd option MROUTING 415Includes support for IP multicast routers. 416Multicast routing is controlled by the 417.Xr mrouted 8 418daemon. 419.It Cd option ND6_DEBUG 420The option sets the default value of 421.Em net.inet6.icmp6.nd6_debug 422to 1, 423for debugging IPv6 neighbor discovery protocol handling. 424See 425.Xr sysctl 2 . 426.It Cd option PIPEX 427Includes pipex in-kernel acceleration for PPPoE, L2TP or PPTP. 428See 429.Xr pipex 4 . 430.It Cd option PPP_BSDCOMP 431Enables BSD compressor for PPP connections. 432.It Cd option PPP_DEFLATE 433For use in conjunction with PPP_BSDCOMP; provides an interface to zlib for PPP 434for deflate compression/decompression. 435.It Cd option PPPOE_TERM_UNKNOWN_SESSIONS 436Send PADT to terminate open sessions before connecting. 437See 438.Xr pppoe 4 . 439.It Cd option SOCKET_SPLICE 440Enables zero-copy socket splicing in the kernel. 441See 442.Dv SO_SPLICE 443in 444.Xr setsockopt 2 445and 446.Xr sosplice 9 . 447.It Cd option TCP_ECN 448Turns on Explicit Congestion Notification (RFC 3168). 449.Em ECN 450allows intermediate routers to use the Congestion Experienced 451codepoint in the IP header as an indication of congestion, and allows 452TCP to adjust the transmission rate using this signal. 453Both communication endpoints negotiate enabling 454.Em ECN 455functionality at the TCP connection establishment. 456.It Cd option TCP_SIGNATURE 457Turns on support for the TCP MD5 Signature option (RFC 2385). 458This is used by 459Internet backbone routers to provide per-packet authentication for the TCP 460packets used to communicate BGP routing information. 461You will also need a 462routing daemon that supports this option in order to actually use it. 463.El 464.Sh OPERATION RELATED OPTIONS 465.Bl -ohang -compact 466.It Cd option BUFPAGES= Ns Ar value 467This option sets the number of pages available for the buffer cache. 468The default value is machine dependent, often calculated as 469between 5% and 10% of total available RAM. 470.Pp 471.It Cd option DST= Ns Ar value 472If 473.Ar value 474is non-zero, indicates that the hardware real-time clock device 475is one hour ahead of the offset given in 476.Sq TIMEZONE , 477due to Daylight Saving Time (DST). 478If 479.Ar value 480is zero, the hardware real-time clock device is not in Daylight Saving Time. 481.Pp 482.It Cd option NKMEMPAGES= Ns Ar value 483.It Cd option NKMEMPAGES_MAX= Ns Ar value 484Size of kernel malloc area in PAGE_SIZE-sized logical pages. 485This area is covered by the kernel submap 486.Em kmem_map . 487The kernel attempts to auto-size this map based on the amount of 488physical memory in the system. 489Platform-specific code may place bounds on this computed size, 490which may be viewed with the 491.Xr sysctl 8 492variable 493.Em vm.nkmempages . 494See 495.Pa /usr/include/machine/param.h 496for the default upper bound. 497The related option 498.Sq NKMEMPAGES_MAX 499allows the bounds to be overridden in the kernel configuration file 500in the event the computed value is insufficient resulting in an 501.Dq out of space in kmem_map 502panic. 503.Pp 504.It Cd option \&"TIMEZONE= Ns Ar value Ns Cm \&" 505.Ar value 506indicates the time zone offset of the hardware real-time clock device, 507in minutes, 508from UTC. 509It is useful when the hardware real-time clock device is configured 510with local time, 511when dual-booting 512.Ox 513with other operating systems on a single machine. 514For instance, if the hardware real-time clock is set to Tokyo time, 515.Ar value 516should be 517.Li \&-540 518as Tokyo local time is 9 hours ahead of UTC. 519Double quotes are needed when specifying a negative 520.Ar value . 521.El 522.Sh SCSI SUBSYSTEM OPTIONS 523See 524.Xr scsi 4 . 525.Bl -ohang 526.It Cd option SCSI_DELAY= Ns Ar value 527Delay for 528.Ar value 529seconds before starting to probe the first SCSI bus. 530This can be used if a SCSI device needs extra time to get ready. 531.It Cd option SCSIDEBUG 532Enable printing of SCSI subsystem debugging info to the console. 533Each of 534.Em SCSIDEBUG_LEVEL , 535.Em SCSIDEBUG_BUSES , 536.Em SCSIDEBUG_TARGETS 537and 538.Em SCSIDEBUG_LUNS 539must have non-zero values for any debugging info to be printed. 540Only 541.Em SCSIDEBUG_LEVEL 542has a default value (SDEV_DB1 | SDEV_DB2) that is non-zero. 543.It Cd option SCSIDEBUG_BUSES= Ns Ar value 544Define which SCSI buses will print debug info. 545Each bit enables debugging info for the corresponding bus. 546e.g. a value of 0x1 enables debug info for bus 0. 547.It Cd option SCSIDEBUG_LEVEL= Ns Ar value 548Define which of the four levels of debugging info are printed. 549Each bit enables a level, and multiple levels are specified by setting multiple 550bits. 551.Bd -literal -offset indent 5520x0010 (SDEV_DB1) SCSI commands, errors, and data 5530x0020 (SDEV_DB2) routine flow 5540x0040 (SDEV_DB3) routine internals 5550x0080 (SDEV_DB4) miscellaneous addition debugging 556.Ed 557.Pp 558If 559.Em SCSIDEBUG_LEVEL 560is undefined, a value of 0x0030 (SDEV_DB1|SDEV_DB2) is used. 561.It Cd option SCSIDEBUG_LUNS= Ns Ar value 562Define which SCSI luns will print debug info. 563Each bit enables debugging info for the corresponding lun. 564.It Cd option SCSIDEBUG_TARGETS= Ns Ar value 565Define which SCSI targets will print debug info. 566Each bit enables debugging info for the corresponding target. 567.It Cd option SCSITERSE 568Terser SCSI error messages. 569This omits the table for decoding ASC/ASCQ info, saving about 30KB. 570.El 571.Sh SYSTEM V IPC OPTIONS 572.Bl -ohang 573.It Cd option SEMMNI= Ns Ar value 574Number of semaphore identifiers (also called semaphore handles 575and semaphore sets) available in the system. 576Default value is 10. 577The kernel allocates memory for the control structures at startup, 578so arbitrarily large values should be avoided. 579.It Cd option SEMMNS= Ns Ar value 580Maximum number of semaphores in all sets in the system. 581Default value is 60. 582.It Cd option SEMMNU= Ns Ar value 583Maximum number of semaphore undo structures in the system. 584Default value is 30. 585.It Cd option SEMUME= Ns Ar value 586Maximum number of per-process undo operation entries in the 587system. 588Semaphore undo operations are invoked by the kernel when 589.Xr semop 2 590is called with the SEM_UNDO flag and the process holding 591the semaphores terminates unexpectedly. 592Default value is 10. 593.It Cd option SHMMAXPGS= Ns Ar value 594Sets the maximum number of 595.At V 596style shared memory pages that are available through the 597.Xr shmget 2 598system call. 599Default value is 1024 on most architectures. 600See 601.Pa /usr/include/machine/vmparam.h 602for the default. 603.It Cd option SYSVMSG 604Includes support for 605.At V 606style message queues. 607See 608.Xr msgctl 2 , 609.Xr msgget 2 , 610.Xr msgrcv 2 , 611.Xr msgsnd 2 . 612.It Cd option SYSVSEM 613Includes support for 614.At V 615style semaphores. 616See 617.Xr semctl 2 , 618.Xr semget 2 , 619.Xr semop 2 . 620.It Cd option SYSVSHM 621Includes support for 622.At V 623style shared memory. 624See 625.Xr shmat 2 , 626.Xr shmctl 2 , 627.Xr shmdt 2 , 628.Xr shmget 2 . 629.El 630.Sh SEE ALSO 631.Xr intro 4 , 632.Xr files.conf 5 , 633.Xr config 8 , 634.Xr sysctl 8 635.Sh HISTORY 636The 637.Nm 638man page first appeared in 639.Ox 2.3 . 640