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