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