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