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. 117The kernel normally uses an environment prepared for it at boot time 118by 119.Xr loader 8 . 120This directive makes the kernel ignore the boot environment and use 121the compiled-in environment instead, unless the boot environment contains 122.Va static_env.disabled=1 . 123.Pp 124This directive is useful for setting kernel tunables in 125embedded environments that do not start from 126.Xr loader 8 . 127.Pp 128All 129.Ic env 130and 131.Ic envvar 132directives will be processed and added to the static environment in reversed 133order of appearance so that later specified variables properly override earlier 134specified variables. 135Note that within 136.Ar filename , 137the first appearance of a given variable will be the first one seen by the 138kernel, effectively shadowing any later appearances of the same variable within 139.Ar filename . 140.\" -------- ENVVAR -------- 141.Pp 142.It Ic envvar Ar setting 143Specifies an individual environment setting to be added to the kernel's 144compiled-in environment. 145.Ar setting 146must be of the form 147.Dq Va name=value . 148Optional quotes are supported in both name and value. 149.Pp 150All 151.Ic env 152and 153.Ic envvar 154directives will be processed and added to the static environment in reversed 155order of appearance so that later specified variables properly override earlier 156specified variables. 157.\" -------- FILES -------- 158.Pp 159.It Ic files Ar filename 160Specifies a file containing a list of files specific to that kernel 161configuration file (a la 162.Pa files. Ns Aq Ar arch ) . 163.\" -------- HINTS -------- 164.Pp 165.It Ic hints Ar filename 166Specifies a file to load a static device configuration specification 167from. 168From 169.Fx 5.0 170onwards, the kernel reads the system's device configuration at boot 171time (see 172.Xr device.hints 5 ) . 173This directive configures the kernel to use the static device configuration 174listed in 175.Ar filename , 176unless the boot environment contains 177.Va static_hints.disabled=1 . 178The file 179.Ar filename 180must conform to the syntax specified by 181.Xr device.hints 5 . 182Multiple hints lines are allowed. 183The resulting hints will be the files concatenated in reverse order of 184appearance so that hints in later files properly override hints in earlier 185files. 186.\" -------- IDENT -------- 187.Pp 188.It Ic ident Ar name 189Set the kernel name to 190.Ar name . 191At least one 192.Ic ident 193directive is required. 194.\" -------- INCLUDE -------- 195.Pp 196.It Ic include Ar filename 197Read subsequent text from file 198.Ar filename 199and return to the current file after 200.Ar filename 201is successfully processed. 202.\" -------- MACHINE -------- 203.Pp 204.It Ic machine Ar arch Op Ar cpuarch 205Specifies the architecture of the machine the kernel is being 206compiled for. 207Legal values for 208.Ar arch 209include: 210.Pp 211.Bl -tag -width ".Cm powerpc" -compact 212.It Cm alpha 213The DEC Alpha architecture. 214.It Cm arm 215The ARM architecture. 216.It Cm amd64 217The AMD x86-64 architecture. 218.It Cm i386 219The Intel x86 based PC architecture. 220.It Cm mips 221The MIPS architecture. 222.It Cm powerpc 223The IBM PowerPC architecture. 224.It Cm sparc64 225The Sun Sparc64 architecture. 226.El 227.Pp 228If argument 229.Ar cpuarch 230is specified, it points 231.Xr config 8 232to the cpu architecture of the machine. 233When 234.Ar cpuarch 235is not specified, it is assumed to be the same as 236.Ar arch . 237.Ar arch 238corresponds to MACHINE. 239.Ar cpuarch 240corresponds to MACHINE_ARCH. 241.Pp 242A kernel configuration file may have only one 243.Ic machine 244directive. 245.\" -------- MAKEOPTION -------- 246.Pp 247.It Ic makeoption Ar options 248.It Ic makeoptions Ar options 249Add 250.Ar options 251to the generated makefile. 252.Pp 253The 254.Ar options 255argument is a comma separated list of one or more option 256specifications. 257Each option specification has the form 258.Pp 259.D1 Ar MakeVariableName Ns Op = Ns Ar Value 260.D1 Ar MakeVariableName Ns += Ns Ar Value 261.Pp 262and results in the appropriate 263.Xr make 1 264variable definition being inserted into the generated makefile. 265If only the name of the 266.Xr make 1 267variable is specified, 268.Ar value 269is assumed to be the empty string. 270.Pp 271Example: 272.Bd -literal -offset indent -compact 273makeoptions MYMAKEOPTION="foo" 274makeoptions MYMAKEOPTION+="bar" 275makeoptions MYNULLMAKEOPTION 276.Ed 277.\" -------- MAXUSERS -------- 278.Pp 279.It Ic maxusers Ar number 280This optional directive is used to configure the size 281of some kernel data structures. 282The parameter 283.Ar number 284can be 0 (the default) or an integer greater than or equal to 2. 285A value of 0 indicates that the kernel should configure 286its data structures according to the size of available 287physical memory. 288If auto configuration is requested, the kernel will set 289this tunable to a value between 32 and 384. 290.Pp 291As explained in 292.Xr tuning 7 , 293this tunable can also be set at boot time using 294.Xr loader 8 . 295.\" -------- NOCPU -------- 296.Pp 297.It Ic nocpu Ar cputype 298Remove the specified CPU 299from the list of previously selected CPUs. 300This directive can be used to cancel the effect of 301.Ic cpu 302directives in files included using 303.Ic include . 304.\" -------- NODEVICE -------- 305.Pp 306.It Ic nodevice Ar name Op , Ar name Op ... 307.It Ic nodevices Ar name Op , Ar name Op ... 308Remove the specified devices 309from the list of previously selected devices. 310This directive can be used to cancel the effects of 311.Ic device 312or 313.Ic devices 314directives in files included using 315.Ic include . 316.\" -------- NOMAKEOPTION -------- 317.Pp 318.It Ic nomakeoption Ar name 319.It Ic nomakeoptions Ar name 320Removes previously defined 321.Xr make 1 322option 323.Ar name 324from the kernel build. 325This directive can be used to cancel the effects of 326.Ic makeoption 327directives in files included using 328.Ic include . 329.\" -------- NOOPTION -------- 330.Pp 331.It Ic nooption Ar name Op , Ar name Op ... 332.It Ic nooptions Ar name Op , Ar name Op ... 333Remove the specified kernel options 334from the list of previously defined options. 335This directive can be used to cancel the effects of 336.Ic option 337or 338.Ic options 339directives in files included using 340.Ic include . 341.\" -------- OPTIONS -------- 342.Pp 343.It Ic option Ar optionspec Op , Ar optionspec Op ... 344.It Ic options Ar optionspec Op , Ar optionspec Op ... 345Add compile time kernel options to the kernel build. 346Each option specification has the form 347.Pp 348.D1 Ar name Ns Op = Ns Ar value 349.Pp 350If 351.Ar value 352is not specified, it is assumed to be 353.Dv NULL . 354Options common to all architectures are specified in 355the file 356.Pa sys/conf/options . 357Options specific to architecture 358.Ar arch 359are specified in the file 360.Pa sys/conf/options. Ns Aq Ar arch . 361.\" -------- PROFILE -------- 362.Pp 363.It Ic profile Ar number 364Enables kernel profiling if 365.Ar number 366is non-zero. 367If 368.Ar number 369is 2 or greater, the kernel is configured for 370high-resolution profiling. 371Kernels can also be built for profiling using the 372.Fl p 373option to 374.Xr config 8 . 375.El 376.Ss Obsolete Directives 377The following kernel configuration directives are obsolete. 378.Bl -tag -width indent 379.\" -------- CONFIG -------- 380.It Ic config 381This directive was used to specify the device to be used for the root 382file system. 383From 384.Fx 4.0 385onwards, this information is passed to a booting kernel by 386.Xr loader 8 . 387.El 388.Sh FILES 389.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 390.It Pa sys/compile/ Ns Ar NAME 391Compile directory created from a kernel configuration. 392.It Pa sys/conf/Makefile. Ns Ar arch 393.Pa Makefile 394fragments for architecture 395.Ar arch . 396.It Pa sys/conf/files 397Devices common to all architectures. 398.It Pa sys/conf/files. Ns Ar arch 399Devices for architecture 400.Ar arch . 401.It Pa sys/conf/options 402Options common to all architectures. 403.It Pa sys/conf/options. Ns Ar arch 404Options for architecture 405.Ar arch . 406.El 407.Sh SEE ALSO 408.Xr kenv 1 , 409.Xr make 1 , 410.Xr device.hints 5 , 411.Xr loader.conf 5 , 412.Xr config 8 , 413.Xr kldload 8 , 414.Xr loader 8 415.Rs 416.%T "Building 4.4BSD Kernels with Config" 417.%A "Samuel J. Leffler" 418.%A "Michael J. Karels" 419.Re 420.Sh HISTORY 421The 422.Xr config 8 423utility first appeared in 424.Bx 4.1 , 425and was subsequently revised in 426.Bx 4.4 . 427.Pp 428The kernel configuration mechanism changed further in 429.Fx 4.0 430and 431.Fx 5.0 , 432moving toward an architecture supporting dynamic kernel 433configuration. 434