1.\" Copyright (c) 2003 Joseph Koshy 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd October 17, 2022 25.Dt CONFIG 5 26.Os 27.Sh NAME 28.Nm config 29.Nd kernel configuration file format 30.Sh DESCRIPTION 31A kernel configuration file specifies the configuration of a 32.Fx 33kernel. 34It is processed by 35.Xr config 8 36to create a build environment where a kernel may be built using 37.Xr make 1 . 38.Ss Lexical Structure 39A kernel configuration file comprises a sequence of specification 40directives. 41.Pp 42A specification directive starts with a keyword at the beginning 43of the line and is followed by additional parameters. 44.Pp 45A specification directive may be terminated by a semicolon 46.Ql \&; 47or by a newline. 48Long input lines may be broken into shorter lines by starting the 49second and subsequent lines with a white space character. 50.Pp 51Case is significant, 52.Dq Li machine 53and 54.Dq Li MACHINE 55are different tokens. 56.Pp 57A double quote character 58.Ql \[dq] 59starts a quoted string. 60All characters up to the next quote character form the value 61of the quoted string. 62A 63.Ql \[dq] 64character may be inserted into a quoted string by 65using the sequence 66.Ql \e\[dq] . 67.Pp 68Numbers are specified using 69.Tn C Ns -style 70syntax. 71.Pp 72A 73.Ql # 74character starts a comment; all characters from the 75.Ql # 76character till the end of the current line are ignored. 77.Pp 78Whitespace between tokens is ignored, except inside quoted strings. 79Whitespace following a comment line is ignored. 80.Ss Configuration Directives 81Kernel configuration directives may appear in any order 82in a kernel configuration file. 83Directives are processed in order of appearance with subsequent 84directive lines overriding the effect of prior ones. 85.Pp 86The list of keywords and their meanings are as follows: 87.Pp 88.Bl -tag -width indent -compact 89.\" -------- CPU -------- 90.It Ic cpu Ar cputype 91Specify the CPU this kernel will run on. 92There can be more than one 93.Ic cpu 94directive in a configuration file. 95The allowed list of CPU names is architecture specific and is 96defined in the file 97.Pa sys/conf/options . Ns Aq Ar arch . 98.\" -------- DEVICE -------- 99.Pp 100.It Ic device Ar name Op , Ar name Op ... 101.It Ic devices Ar name Op , Ar name Op ... 102Configures the specified devices 103for inclusion into the kernel image. 104Devices that are common to all architectures are 105defined in the file 106.Pa sys/conf/files . 107Devices that are specific to architecture 108.Ar arch 109are defined in the file 110.Pa sys/conf/files . Ns Aq Ar arch . 111.\" -------- ENV -------- 112.Pp 113.It Ic env Ar filename 114Specifies a filename containing a kernel environment definition. 115.Pp 116The kernel will augment this compiled-in environment with the environment 117prepared for it at boot time by 118.Xr loader 8 . 119Environment variables specified in the 120.Xr loader 8 121environment will take precedence over environment variables specified in 122.Ar filename , 123and environment variables specified in the dynamic environment take precedence 124over both of these. 125.Pp 126.Va loader_env.disabled=1 127may be specified in the static environment to disable the 128.Xr loader 8 129environment. 130Disabling the 131.Xr loader 8 132should be done with caution and due consideration for whether or not it supplies 133environment variables needed for properly booting the system. 134.Pp 135.Va static_env.disabled=1 136may be specified in the 137.Xr loader 8 138environment to disable use of the static environment. 139This option has no effect if specified in any environment after the 140.Xr loader 8 141environment is processed. 142This option is not usable in conjunction with 143.Va loader_env.disabled . 144.Pp 145This directive is useful for setting kernel tunables in 146embedded environments that do not start from 147.Xr loader 8 . 148.Pp 149All 150.Ic env 151and 152.Ic envvar 153directives will be processed and added to the static environment in reversed 154order of appearance so that later specified variables properly override earlier 155specified variables. 156Note that within 157.Ar filename , 158the first appearance of a given variable will be the first one seen by the 159kernel, effectively shadowing any later appearances of the same variable within 160.Ar filename . 161.\" -------- ENVVAR -------- 162.Pp 163.It Ic envvar Ar setting 164Specifies an individual environment setting to be added to the kernel's 165compiled-in environment. 166.Ar setting 167must be of the form 168.Dq Va name=value . 169Optional quotes are supported in both name and value. 170.Pp 171All 172.Ic env 173and 174.Ic envvar 175directives will be processed and added to the static environment in reversed 176order of appearance so that later specified variables properly override earlier 177specified variables. 178.\" -------- FILES -------- 179.Pp 180.It Ic files Ar filename 181Specifies a file containing a list of files specific to that kernel 182configuration file (a la 183.Pa files . Ns Aq Ar arch ) . 184.\" -------- HINTS -------- 185.Pp 186.It Ic hints Ar filename 187Specifies a file to load a static device configuration specification 188from. 189From 190.Fx 5.0 191onwards, the kernel reads the system's device configuration at boot 192time (see 193.Xr device.hints 5 ) . 194This directive configures the kernel to use the static device configuration 195listed in 196.Ar filename . 197.Pp 198Hints provided in this static device configuration will be overwritten in the 199order in which they're encountered. 200Hints in the compiled-in environment takes precedence over compiled-in hints, 201and hints in the environment prepared for the kernel by 202.Xr loader 8 203takes precedence over hints in the compiled-in environment. 204.Pp 205Once the dynamic environment becomes available, all compiled-in hints will be 206added to the dynamic environment if they do not already have an override in 207the dynamic environment. 208The dynamic environment will then be used for all searches of hints. 209.Pp 210.Va static_hints.disabled=1 211may be specified in either a compiled-in environment or the 212.Xr loader 8 213environment to disable use of these hints files. 214This option has no effect if specified in any environment after the 215.Xr loader 8 216environment is processed. 217.Pp 218The file 219.Ar filename 220must conform to the syntax specified by 221.Xr device.hints 5 . 222Multiple hints lines are allowed. 223The resulting hints will be the files concatenated in reverse order of 224appearance so that hints in later files properly override hints in earlier 225files. 226.\" -------- IDENT -------- 227.Pp 228.It Ic ident Ar name 229Set the kernel name to 230.Ar name . 231At least one 232.Ic ident 233directive is required. 234.\" -------- INCLUDE -------- 235.Pp 236.It Ic include Ar filename 237Read subsequent text from file 238.Ar filename 239and return to the current file after 240.Ar filename 241is successfully processed. 242.\" -------- MACHINE -------- 243.Pp 244.It Ic machine Ar arch Op Ar cpuarch 245Specifies the architecture of the machine the kernel is being 246compiled for. 247Legal values for 248.Ar arch 249include: 250.Pp 251.Bl -tag -width ".Cm powerpc" -compact 252.It Cm arm64 253The 64-bit ARM application architecture. 254.It Cm arm 255The ARM architecture 256.It Cm amd64 257The AMD x86-64 architecture. 258.It Cm i386 259The Intel x86 based PC architecture. 260.It Cm powerpc 261The IBM PowerPC architecture. 262.It Cm riscv 263The RISC-V architecture. 264.El 265.Pp 266If argument 267.Ar cpuarch 268is specified, it points 269.Xr config 8 270to the cpu architecture of the machine. 271When 272.Ar cpuarch 273is not specified, it is assumed to be the same as 274.Ar arch . 275.Ar arch 276corresponds to MACHINE. 277.Ar cpuarch 278corresponds to MACHINE_ARCH. 279.Pp 280A kernel configuration file may have only one 281.Ic machine 282directive, unless the second one matches the 283machine argument in the first one exactly. 284.\" -------- MAKEOPTION -------- 285.Pp 286.It Ic makeoption Ar options 287.It Ic makeoptions Ar options 288Add 289.Ar options 290to the generated makefile. 291.Pp 292The 293.Ar options 294argument is a comma separated list of one or more option 295specifications. 296Each option specification has the form 297.Pp 298.D1 Ar MakeVariableName Ns Op = Ns Ar Value 299.D1 Ar MakeVariableName Ns += Ns Ar Value 300.Pp 301and results in the appropriate 302.Xr make 1 303variable definition being inserted into the generated makefile. 304If only the name of the 305.Xr make 1 306variable is specified, 307.Ar value 308is assumed to be the empty string. 309.Pp 310Example: 311.Bd -literal -offset indent -compact 312makeoptions MYMAKEOPTION="foo" 313makeoptions MYMAKEOPTION+="bar" 314makeoptions MYNULLMAKEOPTION 315.Ed 316.\" -------- MAXUSERS -------- 317.Pp 318.It Ic maxusers Ar number 319This optional directive is used to configure the size 320of some kernel data structures. 321The parameter 322.Ar number 323can be 0 (the default) or an integer greater than or equal to 2. 324A value of 0 indicates that the kernel should configure 325its data structures according to the size of available 326physical memory. 327If auto configuration is requested, the kernel will set 328this tunable to a value between 32 and 384 for 32-bit systems, 329or scale the value higher based on available memory for 64-bit 330systems. 331.Pp 332As explained in 333.Xr tuning 7 , 334this tunable can also be set at boot time using 335.Xr loader 8 . 336.\" -------- NOCPU -------- 337.Pp 338.It Ic nocpu Ar cputype 339Remove the specified CPU 340from the list of previously selected CPUs. 341This directive can be used to cancel the effect of 342.Ic cpu 343directives in files included using 344.Ic include . 345.\" -------- NODEVICE -------- 346.Pp 347.It Ic nodevice Ar name Op , Ar name Op ... 348.It Ic nodevices Ar name Op , Ar name Op ... 349Remove the specified devices 350from the list of previously selected devices. 351This directive can be used to cancel the effects of 352.Ic device 353or 354.Ic devices 355directives in files included using 356.Ic include . 357.\" -------- NOMAKEOPTION -------- 358.Pp 359.It Ic nomakeoption Ar name 360.It Ic nomakeoptions Ar name 361Removes previously defined 362.Xr make 1 363option 364.Ar name 365from the kernel build. 366This directive can be used to cancel the effects of 367.Ic makeoption 368directives in files included using 369.Ic include . 370.\" -------- NOOPTION -------- 371.Pp 372.It Ic nooption Ar name Op , Ar name Op ... 373.It Ic nooptions Ar name Op , Ar name Op ... 374Remove the specified kernel options 375from the list of previously defined options. 376This directive can be used to cancel the effects of 377.Ic option 378or 379.Ic options 380directives in files included using 381.Ic include . 382.\" -------- OPTIONS -------- 383.Pp 384.It Ic option Ar optionspec Op , Ar optionspec Op ... 385.It Ic options Ar optionspec Op , Ar optionspec Op ... 386Add compile time kernel options to the kernel build. 387Each option specification has the form 388.Pp 389.D1 Ar name Ns Op = Ns Ar value 390.Pp 391If 392.Ar value 393is not specified, it is assumed to be 394.Dv NULL . 395Options common to all architectures are specified in 396the file 397.Pa sys/conf/options . 398Options specific to architecture 399.Ar arch 400are specified in the file 401.Pa sys/conf/options . Ns Aq Ar arch . 402.El 403.Sh FILES 404.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 405.It Pa sys/compile/ Ns Ar NAME 406Compile directory created from a kernel configuration. 407.It Pa sys/conf/Makefile . Ns Ar arch 408.Pa Makefile 409fragments for architecture 410.Ar arch . 411.It Pa sys/conf/files 412Devices common to all architectures. 413.It Pa sys/conf/files . Ns Ar arch 414Devices for architecture 415.Ar arch . 416.It Pa sys/conf/options 417Options common to all architectures. 418.It Pa sys/conf/options . Ns Ar arch 419Options for architecture 420.Ar arch . 421.El 422.Sh SEE ALSO 423.Xr kenv 1 , 424.Xr make 1 , 425.Xr device.hints 5 , 426.Xr loader.conf 5 , 427.Xr config 8 , 428.Xr kldload 8 , 429.Xr loader 8 430.Rs 431.%T "Building 4.4BSD Kernels with Config" 432.%A "Samuel J. Leffler" 433.%A "Michael J. Karels" 434.Re 435.Sh HISTORY 436The 437.Xr config 8 438utility first appeared in 439.Bx 4.1 , 440and was subsequently revised in 441.Bx 4.4 . 442.Pp 443The kernel configuration mechanism changed further in 444.Fx 4.0 445and 446.Fx 5.0 , 447moving toward an architecture supporting dynamic kernel 448configuration. 449