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