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