usr.sbin/config/config.5

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