stand/defaults/loader.conf.5

   1 .\" Copyright (c) 1999 Daniel C. Sobral
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .Dd July 31, 2021
  27 .Dt LOADER.CONF 5
  28 .Os
  29 .Sh NAME
  30 .Nm loader.conf
  31 .Nd "system bootstrap configuration information"
  32 .Sh DESCRIPTION
  33 The file
  34 .Nm
  35 contains descriptive information on bootstrapping the system.
  36 Through
  37 it you can specify the kernel to be booted, parameters to be passed to
  38 it, and additional modules to be loaded; and generally set all variables
  39 described in
  40 .Xr loader 8 .
  41 .Sh SYNTAX
  42 Though
  43 .Nm Ns 's
  44 format was defined explicitly to resemble
  45 .Xr rc.conf 5 ,
  46 and can be sourced by
  47 .Xr sh 1 ,
  48 some settings are treated in a special fashion.
  49 Also, the
  50 behavior of some settings is defined by the setting's suffix;
  51 the prefix identifies which module the setting controls.
  52 .Pp
  53 The general parsing rules are:
  54 .Bl -bullet
  55 .It
  56 Spaces and empty lines are ignored.
  57 .It
  58 A # sign will mark the remainder of the line as a comment.
  59 .It
  60 Only one setting can be present on each line.
  61 .El
  62 .Pp
  63 All settings have the following format:
  64 .Pp
  65 .Dl variable="value"
  66 .Pp
  67 Unless it belongs to one of the classes of settings that receive special
  68 treatment, a setting will set the value of a
  69 .Xr loader 8
  70 environment variable.
  71 The settings that receive special
  72 treatment are listed below.
  73 Settings beginning with
  74 .Qq *
  75 below define the modules to be loaded and
  76 may have any prefix; the prefix identifies a module.
  77 All such settings sharing a common
  78 prefix refer to the same module.
  79 .Bl -tag -width Ar
  80 .It Ar autoboot_delay
  81 Delay in seconds before automatically booting.
  82 A user with console access will be able to interrupt the
  83 .Ic autoboot
  84 process and escape into the interactive mode by pressing a key on
  85 the console during this delay.
  86 .Pp
  87 If set to
  88 .Dq Li NO ,
  89 no
  90 .Ic autoboot
  91 is automatically attempted after processing
  92 .Pa /boot/loader.rc ,
  93 though explicit
  94 .Ic autoboot Ns 's
  95 are processed normally, using a 10 second delay.
  96 .Pp
  97 If set to
  98 .Dq Li 0 ,
  99 no delay is inserted, but any keys pressed while the kernel and modules are
 100 loaded will enter interactive mode.
 101 .Pp
 102 If set to
 103 .Dq Li -1 ,
 104 no delay will be inserted and
 105 .Nm
 106 starts interactive mode only if
 107 .Ic autoboot
 108 has failed.
 109 In combination with the
 110 .Va beastie_disable
 111 option, this option prevents users with console access from being able
 112 to interrupt the
 113 .Ic autoboot
 114 process and escape to the loader prompt.
 115 To use the
 116 .Va autoboot_delay
 117 option in this manner,
 118 .Va beastie_disable
 119 must be set to
 120 .Dq Li YES .
 121 .It Ar exec
 122 Immediately executes a
 123 .Xr loader 8
 124 command.
 125 This type of setting cannot be processed by programs other
 126 than
 127 .Xr loader 8 ,
 128 so its use should be avoided.
 129 Multiple instances of it will be processed
 130 independently.
 131 .It Ar loader_conf_dirs
 132 Space separated list of directories to process for configuration files.
 133 The lua-based loader will process files with a
 134 .Dq .conf
 135 suffix that are placed in these directories.
 136 .It Ar loader_conf_files
 137 Defines additional configuration files to be processed right after the
 138 present file.
 139 .Ar loader_conf_files
 140 should be treated as write-only.
 141 One cannot depend on any value remaining in the loader environment or carried
 142 over into the kernel environment.
 143 .It Ar kernel
 144 Name of the kernel to be loaded.
 145 If no kernel name is set, no additional
 146 modules will be loaded.
 147 The name must be a subdirectory of
 148 .Pa /boot
 149 that contains a kernel.
 150 .It Ar kernel_options
 151 Flags to be passed to the kernel.
 152 .It Ar vfs.root.mountfrom
 153 Specify the root partition to mount.
 154 For example:
 155 .Pp
 156 .Dl vfs.root.mountfrom="ufs:/dev/da0s1a"
 157 .Pp
 158 .Xr loader 8
 159 automatically calculates the value of this tunable from
 160 .Pa /etc/fstab
 161 from the partition the kernel was loaded from.
 162 The calculated value might be calculated incorrectly when
 163 .Pa /etc/fstab
 164 is not available during
 165 .Xr loader 8
 166 startup (as during diskless booting from NFS), or if a different
 167 device is desired by the user.
 168 The preferred value can be set in
 169 .Pa /loader.conf .
 170 .Pp
 171 The value can also be overridden from the
 172 .Xr loader 8
 173 command line.
 174 This is useful for system recovery when
 175 .Pa /etc/fstab
 176 is damaged, lost, or read from the wrong partition.
 177 .It Ar password
 178 Protect boot menu with a password without interrupting
 179 .Ic autoboot
 180 process.
 181 The password should be in clear text format.
 182 If a password is set, boot menu will not appear until any key is pressed during
 183 countdown period specified by
 184 .Va autoboot_delay
 185 variable or
 186 .Ic autoboot
 187 process fails.
 188 In both cases user should provide specified password to be able to access boot
 189 menu.
 190 .It Ar bootlock_password
 191 Provides a password to be required by check-password before execution is
 192 allowed to continue.
 193 The password should be in clear text format.
 194 If a password is set, the user must provide specified password to boot.
 195 .It Ar verbose_loading
 196 If set to
 197 .Dq YES ,
 198 module names will be displayed as they are loaded.
 199 .It Ar module_blacklist
 200 Blacklist of modules.
 201 Modules specified in the blacklist may not be loaded automatically with a
 202 .Ar *_load
 203 directive, but they may be loaded directly at the
 204 .Xr loader 8
 205 prompt.
 206 Blacklisted modules may still be loaded indirectly as dependencies of other
 207 modules.
 208 .It Ar *_load
 209 If set to
 210 .Dq YES ,
 211 that module will be loaded.
 212 If no name is defined (see below), the
 213 module's name is taken to be the same as the prefix.
 214 .It Ar *_name
 215 Defines the name of the module.
 216 .It Ar *_type
 217 Defines the module's type.
 218 If none is given, it defaults to a kld module.
 219 .It Ar *_flags
 220 Flags and parameters to be passed to the module.
 221 .It Ar *_before
 222 Commands to be executed before the module is loaded.
 223 Use of this setting
 224 should be avoided.
 225 .It Ar *_after
 226 Commands to be executed after the module is loaded.
 227 Use of this setting
 228 should be avoided.
 229 .It Ar *_error
 230 Commands to be executed if the loading of a module fails.
 231 Except for the
 232 special value
 233 .Dq abort ,
 234 which aborts the bootstrap process, use of this setting should be avoided.
 235 .El
 236 .Pp
 237 .Em WARNING :
 238 developers should never use these suffixes for any kernel environment
 239 variables (tunables) or conflicts will result.
 240 .Sh DEFAULT SETTINGS
 241 Most of
 242 .Nm Ns 's
 243 default settings can be ignored.
 244 The few of them which are important
 245 or useful are:
 246 .Bl -tag -width bootfile -offset indent
 247 .It Va bitmap_load
 248 .Pq Dq NO
 249 If set to
 250 .Dq YES ,
 251 a bitmap will be loaded to be displayed on screen while booting.
 252 .It Va bitmap_name
 253 .Pq Dq Pa /boot/splash.bmp
 254 Name of the bitmap to be loaded.
 255 Any other name can be used.
 256 .It Va comconsole_speed
 257 .Dq ( 9600
 258 or the value of the
 259 .Va BOOT_COMCONSOLE_SPEED
 260 variable when
 261 .Xr loader 8
 262 was compiled).
 263 Sets the speed of the serial console.
 264 If the previous boot loader stage specified that a serial console
 265 is in use then the default speed is determined from the current
 266 serial port speed setting.
 267 .It Va console
 268 .Pq Dq vidconsole
 269 .Dq comconsole
 270 selects serial console,
 271 .Dq vidconsole
 272 selects the video console,
 273 .Dq efi
 274 selects the EFI console,
 275 .Dq nullconsole
 276 selects a mute console
 277 (useful for systems with neither a video console nor a serial port), and
 278 .Dq spinconsole
 279 selects the video console which prevents any input and hides all output
 280 replacing it with
 281 .Dq spinning
 282 character (useful for embedded products and such).
 283 .It Va screen.font
 284 Set font size for framebuffer mode.
 285 Default font size is selected based on screen resolution, to achieve
 286 terminal dimensions 80x24.
 287 .It Va screen.textmode
 288 Value
 289 .Dq 0
 290 will trigger BIOS loader to switch to use VESA BIOS Extension (VBE)
 291 frame buffer mode for console.
 292 The same effect can be achieved by setting
 293 .Va vbe_max_resolution .
 294 .Pp
 295 Value
 296 .Dq 1
 297 will force BIOS loader to use VGA text mode.
 298 .Pp
 299 If
 300 .Va vbe_max_resolution
 301 is not set, the loader will try to set screen resolution based on EDID
 302 information.
 303 If EDID is not available, the default resolution is 800x600 (if available).
 304 .It Va screen.height
 305 .It Va screen.width
 306 .It Va screen.depth
 307 .Va screen.height ,
 308 .Va screen.width ,
 309 .Va screen.depth
 310 are set by loader when loader is using framebuffer mode to draw the screen.
 311 .It Va efi_max_resolution
 312 .It Va vbe_max_resolution
 313 Specify the maximum desired resolution for the EFI or VBE framebuffer console.
 314 The following values are accepted:
 315 .Bl -column "WidthxHeight"
 316 .It Sy Value Ta Sy Resolution
 317 .It 480p Ta 640x480
 318 .It 720p Ta 1280x720
 319 .It 1080p Ta 1920x1080
 320 .It 2160p Ta 3840x2160
 321 .It 4k Ta 3840x2160
 322 .It 5k Ta 5120x2880
 323 .It Va Width Ns x Ns Va Height Ta Va Width Ns x Ns Va Height
 324 .El
 325 .It Va kernel
 326 .Pq Dq kernel
 327 .It Va kernels
 328 .Pq Dq kernel kernel.old
 329 Space or comma separated list of kernels to present in the boot menu.
 330 .It Va loader_conf_files
 331 .Pq Dq Pa /boot/loader.conf /boot/loader.conf.local
 332 .It Va loader_conf_dirs
 333 .Pq Dq Pa /boot/loader.conf.d
 334 .It Va splash_bmp_load
 335 .Pq Dq NO
 336 If set to
 337 .Dq YES ,
 338 will load the splash screen module, making it possible to display a bmp image
 339 on the screen while booting.
 340 .It Va splash_pcx_load
 341 .Pq Dq NO
 342 If set to
 343 .Dq YES ,
 344 will load the splash screen module, making it possible to display a pcx image
 345 on the screen while booting.
 346 .It Va vesa_load
 347 .Pq Dq NO
 348 If set to
 349 .Dq YES ,
 350 the vesa module will be loaded, enabling bitmaps above VGA resolution to
 351 be displayed.
 352 .It Va beastie_disable
 353 If set to
 354 .Dq YES ,
 355 the beastie boot menu will be skipped.
 356 .It Va loader_logo Pq Dq Li orbbw
 357 Selects a desired logo in the beastie boot menu.
 358 Possible values are:
 359 .Dq Li orbbw ,
 360 .Dq Li orb ,
 361 .Dq Li fbsdbw ,
 362 .Dq Li beastiebw ,
 363 .Dq Li beastie ,
 364 and
 365 .Dq Li none .
 366 .It Va loader_color
 367 If set to
 368 .Dq NO ,
 369 the beastie boot menu will be displayed without ANSI coloring.
 370 .It Va entropy_cache_load
 371 .Pq Dq YES
 372 If set to
 373 .Dq NO ,
 374 the very early
 375 boot-time entropy file
 376 will not be loaded.
 377 See the entropy entries in
 378 .Xr rc.conf 5 .
 379 .It Va entropy_cache_name
 380 .Pq Dq /boot/entropy
 381 The name of the very early
 382 boot-time entropy cache file.
 383 .It Va cpu_microcode_load
 384 .Pq Dq NO
 385 If set to
 386 .Dq YES ,
 387 the microcode update file specified by
 388 .Va cpu_microcode_name
 389 will be loaded and applied very early during boot.
 390 This provides functionality similar to
 391 .Xr cpucontrol 8
 392 but ensures that CPU features enabled by microcode updates can be
 393 used by the kernel.
 394 The update will be re-applied automatically when resuming from an
 395 ACPI sleep state.
 396 If the update file contains updates for multiple processor models,
 397 the kernel will search for and extract a matching update.
 398 Currently this setting is supported only on Intel
 399 .Dv i386
 400 and
 401 .Dv amd64
 402 processors.
 403 It has no effect on other processor types.
 404 .It Va cpu_microcode_name
 405 A path to a microcode update file.
 406 .El
 407 .Sh OTHER SETTINGS
 408 Other settings that may be used in
 409 .Nm
 410 that have no default value:
 411 .Bl -tag -width bootfile -offset indent
 412 .It Va fdt_overlays
 413 Specifies a comma-delimited list of FDT overlays to apply.
 414 .Pa /boot/dtb/overlays
 415 is created by default for overlays to be placed in.
 416 .It Va kernels_autodetect
 417 If set to
 418 .Dq YES ,
 419 attempt to auto-detect kernels installed in
 420 .Pa /boot .
 421 This is an option specific to the Lua-based loader.
 422 It is not available in the default Forth-based loader.
 423 .El
 424 .Sh FILES
 425 .Bl -tag -width /boot/defaults/loader.conf -compact
 426 .It Pa /boot/defaults/loader.conf
 427 default settings \(em do not change this file.
 428 .It Pa /boot/loader.conf
 429 user defined settings.
 430 .It Pa /boot/loader.conf.lua
 431 user defined settings written in lua.
 432 .It Pa /boot/loader.conf.local
 433 machine-specific settings for sites with a common loader.conf.
 434 .El
 435 .Sh SEE ALSO
 436 .Xr loader.conf.lua 5 ,
 437 .Xr rc.conf 5 ,
 438 .Xr boot 8 ,
 439 .Xr cpucontrol 8 ,
 440 .Xr loader 8 ,
 441 .Xr loader.4th 8
 442 .Sh HISTORY
 443 The file
 444 .Nm
 445 first appeared in
 446 .Fx 3.2 .
 447 .Sh AUTHORS
 448 This manual page was written by
 449 .An Daniel C. Sobral Aq dcs@FreeBSD.org .
 450 .Sh BUGS
 451 The
 452 .Xr loader 8
 453 stops reading
 454 .Nm
 455 when it encounters a syntax error, so any options which are vital for
 456 booting a particular system (i.e.,
 457 .Dq Va hw.ata.ata_dma Ns "=0" )
 458 should precede any experimental additions to
 459 .Nm .