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.\" -------- 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 319Example: 320.Bd -literal -offset indent -compact 321makeoptions MYMAKEOPTION="foo" 322makeoptions MYMAKEOPTION+="bar" 323makeoptions MYNULLMAKEOPTION 324.Ed 325.\" -------- MAXUSERS -------- 326.Pp 327.It Ic maxusers Ar number 328This optional directive is used to configure the size 329of some kernel data structures. 330The parameter 331.Ar number 332can be 0 (the default) or an integer greater than or equal to 2. 333A value of 0 indicates that the kernel should configure 334its data structures according to the size of available 335physical memory. 336If auto configuration is requested, the kernel will set 337this tunable to a value between 32 and 384 for 32-bit systems, 338or scale the value higher based on available memory for 64-bit 339systems. 340.Pp 341As explained in 342.Xr tuning 7 , 343this tunable can also be set at boot time using 344.Xr loader 8 . 345.\" -------- NOCPU -------- 346.Pp 347.It Ic nocpu Ar cputype 348Remove the specified CPU 349from the list of previously selected CPUs. 350This directive can be used to cancel the effect of 351.Ic cpu 352directives in files included using 353.Ic include . 354.\" -------- NODEVICE -------- 355.Pp 356.It Ic nodevice Ar name Op , Ar name Op ... 357.It Ic nodevices Ar name Op , Ar name Op ... 358Remove the specified devices 359from the list of previously selected devices. 360This directive can be used to cancel the effects of 361.Ic device 362or 363.Ic devices 364directives in files included using 365.Ic include . 366.\" -------- NOMAKEOPTION -------- 367.Pp 368.It Ic nomakeoption Ar name 369.It Ic nomakeoptions Ar name 370Removes previously defined 371.Xr make 1 372option 373.Ar name 374from the kernel build. 375This directive can be used to cancel the effects of 376.Ic makeoption 377directives in files included using 378.Ic include . 379.\" -------- NOOPTION -------- 380.Pp 381.It Ic nooption Ar name Op , Ar name Op ... 382.It Ic nooptions Ar name Op , Ar name Op ... 383Remove the specified kernel options 384from the list of previously defined options. 385This directive can be used to cancel the effects of 386.Ic option 387or 388.Ic options 389directives in files included using 390.Ic include . 391.\" -------- OPTIONS -------- 392.Pp 393.It Ic option Ar optionspec Op , Ar optionspec Op ... 394.It Ic options Ar optionspec Op , Ar optionspec Op ... 395Add compile time kernel options to the kernel build. 396Each option specification has the form 397.Pp 398.D1 Ar name Ns Op = Ns Ar value 399.Pp 400If 401.Ar value 402is not specified, it is assumed to be 403.Dv NULL . 404Options common to all architectures are specified in 405the file 406.Pa sys/conf/options . 407Options specific to architecture 408.Ar arch 409are specified in the file 410.Pa sys/conf/options . Ns Aq Ar arch . 411.El 412.Sh FILES 413.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 414.It Pa sys/compile/ Ns Ar NAME 415Compile directory created from a kernel configuration. 416.It Pa sys/conf/Makefile . Ns Ar arch 417.Pa Makefile 418fragments for architecture 419.Ar arch . 420.It Pa sys/conf/files 421Devices common to all architectures. 422.It Pa sys/conf/files . Ns Ar arch 423Devices for architecture 424.Ar arch . 425.It Pa sys/conf/options 426Options common to all architectures. 427.It Pa sys/conf/options . Ns Ar arch 428Options for architecture 429.Ar arch . 430.El 431.Sh SEE ALSO 432.Xr kenv 1 , 433.Xr make 1 , 434.Xr device.hints 5 , 435.Xr loader.conf 5 , 436.Xr config 8 , 437.Xr kldload 8 , 438.Xr loader 8 439.Rs 440.%T "Building 4.4BSD Kernels with Config" 441.%A "Samuel J. Leffler" 442.%A "Michael J. Karels" 443.Re 444.Sh HISTORY 445The 446.Xr config 8 447utility first appeared in 448.Bx 4.1 , 449and was subsequently revised in 450.Bx 4.4 . 451.Pp 452The kernel configuration mechanism changed further in 453.Fx 4.0 454and 455.Fx 5.0 , 456moving toward an architecture supporting dynamic kernel 457configuration. 458