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