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