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