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