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