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