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