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 June 13, 2025 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.\" -------- INCLUDEOPTIONS -------- 243.Pp 244.It Ic includeoptions Ar filename 245Specifies a file containing a list of additional options 246specific to that kernel configuration file. 247This is useful for build environments that need to add 248custom options and is often used in conjunction with the 249.Ic makeoption 250directive. 251.\" -------- MACHINE -------- 252.Pp 253.It Ic machine Ar arch Op Ar cpuarch 254Specifies the architecture of the machine the kernel is being 255compiled for. 256Legal values for 257.Ar arch 258include: 259.Pp 260.Bl -tag -width ".Cm powerpc" -compact 261.It Cm arm64 262The 64-bit ARM application architecture. 263.It Cm arm 264The ARM architecture 265.It Cm amd64 266The AMD x86-64 architecture. 267.It Cm i386 268The Intel x86 based PC architecture. 269.It Cm powerpc 270The IBM PowerPC architecture. 271.It Cm riscv 272The RISC-V architecture. 273.El 274.Pp 275If argument 276.Ar cpuarch 277is specified, it points 278.Xr config 8 279to the cpu architecture of the machine. 280When 281.Ar cpuarch 282is not specified, it is assumed to be the same as 283.Ar arch . 284.Ar arch 285corresponds to MACHINE. 286.Ar cpuarch 287corresponds to MACHINE_ARCH. 288.Pp 289A kernel configuration file may have only one 290.Ic machine 291directive, unless the second one matches the 292machine argument in the first one exactly. 293.\" -------- MAKEOPTION -------- 294.Pp 295.It Ic makeoption Ar options 296.It Ic makeoptions Ar options 297Add 298.Ar options 299to the generated makefile. 300.Pp 301The 302.Ar options 303argument is a comma separated list of one or more option 304specifications. 305Each option specification has the form 306.Pp 307.D1 Ar MakeVariableName Ns Op = Ns Ar Value 308.D1 Ar MakeVariableName Ns += Ns Ar Value 309.Pp 310and results in the appropriate 311.Xr make 1 312variable definition being inserted into the generated makefile. 313If only the name of the 314.Xr make 1 315variable is specified, 316.Ar value 317is assumed to be the empty string. 318.Pp 319Note that, as the common makefiles overwrite the 320.Va CFLAGS 321variable after having processed the configuration file, 322customizing 323.Va CFLAGS 324directly via 325.Ic makeoptions 326is not possible. 327Nonetheless, custom compiler flags can be specified using the 328.Va CONF_CFLAGS 329variable instead. 330Its content is appended to 331.Va CFLAGS 332after the common makefiles have set the latter, allowing to override their 333compilation flags. 334.Pp 335Example: 336.Bd -literal -offset indent -compact 337makeoptions MYMAKEOPTION="foo" 338makeoptions MYMAKEOPTION+="bar" 339makeoptions MYNULLMAKEOPTION 340makeoptions CONF_CFLAGS+="-DSOME_CONTROLLING_MACRO" 341.Ed 342.\" -------- MAXUSERS -------- 343.Pp 344.It Ic maxusers Ar number 345This optional directive is used to configure the size 346of some kernel data structures. 347The parameter 348.Ar number 349can be 0 (the default) or an integer greater than or equal to 2. 350A value of 0 indicates that the kernel should configure 351its data structures according to the size of available 352physical memory. 353If auto configuration is requested, the kernel will set 354this tunable to a value between 32 and 384 for 32-bit systems, 355or scale the value higher based on available memory for 64-bit 356systems. 357.Pp 358As explained in 359.Xr tuning 7 , 360this tunable can also be set at boot time using 361.Xr loader 8 . 362.\" -------- NOCPU -------- 363.Pp 364.It Ic nocpu Ar cputype 365Remove the specified CPU 366from the list of previously selected CPUs. 367This directive can be used to cancel the effect of 368.Ic cpu 369directives in files included using 370.Ic include . 371.\" -------- NODEVICE -------- 372.Pp 373.It Ic nodevice Ar name Op , Ar name Op ... 374.It Ic nodevices Ar name Op , Ar name Op ... 375Remove the specified devices 376from the list of previously selected devices. 377This directive can be used to cancel the effects of 378.Ic device 379or 380.Ic devices 381directives in files included using 382.Ic include . 383.\" -------- NOMAKEOPTION -------- 384.Pp 385.It Ic nomakeoption Ar name 386.It Ic nomakeoptions Ar name 387Removes previously defined 388.Xr make 1 389option 390.Ar name 391from the kernel build. 392This directive can be used to cancel the effects of 393.Ic makeoption 394directives in files included using 395.Ic include . 396.\" -------- NOOPTION -------- 397.Pp 398.It Ic nooption Ar name Op , Ar name Op ... 399.It Ic nooptions Ar name Op , Ar name Op ... 400Remove the specified kernel options 401from the list of previously defined options. 402This directive can be used to cancel the effects of 403.Ic option 404or 405.Ic options 406directives in files included using 407.Ic include . 408.\" -------- OPTIONS -------- 409.Pp 410.It Ic option Ar optionspec Op , Ar optionspec Op ... 411.It Ic options Ar optionspec Op , Ar optionspec Op ... 412Add compile time kernel options to the kernel build. 413Each option specification has the form 414.Pp 415.D1 Ar name Ns Op = Ns Ar value 416.Pp 417If 418.Ar value 419is not specified, it is assumed to be 420.Dv NULL . 421Options common to all architectures are specified in 422the file 423.Pa sys/conf/options . 424Options specific to architecture 425.Ar arch 426are specified in the file 427.Pa sys/conf/options . Ns Aq Ar arch . 428.El 429.Sh FILES 430.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 431.It Pa sys/compile/ Ns Ar NAME 432Compile directory created from a kernel configuration. 433.It Pa sys/conf/Makefile . Ns Ar arch 434.Pa Makefile 435fragments for architecture 436.Ar arch . 437.It Pa sys/conf/files 438Devices common to all architectures. 439.It Pa sys/conf/files . Ns Ar arch 440Devices for architecture 441.Ar arch . 442.It Pa sys/conf/options 443Options common to all architectures. 444.It Pa sys/conf/options . Ns Ar arch 445Options for architecture 446.Ar arch . 447.El 448.Sh SEE ALSO 449.Xr kenv 1 , 450.Xr make 1 , 451.Xr device.hints 5 , 452.Xr loader.conf 5 , 453.Xr config 8 , 454.Xr kldload 8 , 455.Xr loader 8 456.Rs 457.%T "Building 4.4BSD Kernels with Config" 458.%A "Samuel J. Leffler" 459.%A "Michael J. Karels" 460.Re 461.Sh HISTORY 462The 463.Xr config 8 464utility first appeared in 465.Bx 4.1 , 466and was subsequently revised in 467.Bx 4.4 . 468.Pp 469The kernel configuration mechanism changed further in 470.Fx 4.0 471and 472.Fx 5.0 , 473moving toward an architecture supporting dynamic kernel 474configuration. 475