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