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