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