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 March 19, 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 kernel 224.Pq Dq kernel 225.It Va kernels 226.Pq Dq kernel kernel.old 227Space or comma separated list of kernels to present in the boot menu. 228.It Va loader_conf_files 229.Pq Dq Pa /boot/loader.conf /boot/loader.conf.local 230.It Va splash_bmp_load 231.Pq Dq NO 232If set to 233.Dq YES , 234will load the splash screen module, making it possible to display a bmp image 235on the screen while booting. 236.It Va splash_pcx_load 237.Pq Dq NO 238If set to 239.Dq YES , 240will load the splash screen module, making it possible to display a pcx image 241on the screen while booting. 242.It Va vesa_load 243.Pq Dq NO 244If set to 245.Dq YES , 246the vesa module will be loaded, enabling bitmaps above VGA resolution to 247be displayed. 248.It Va beastie_disable 249If set to 250.Dq YES , 251the beastie boot menu will be skipped. 252.It Va loader_logo Pq Dq Li orbbw 253Selects a desired logo in the beastie boot menu. 254Possible values are: 255.Dq Li orbbw , 256.Dq Li orb , 257.Dq Li fbsdbw , 258.Dq Li beastiebw , 259.Dq Li beastie , 260and 261.Dq Li none . 262.It Va loader_color 263If set to 264.Dq NO , 265the beastie boot menu will be displayed without ANSI coloring. 266.It Va entropy_cache_load 267.Pq Dq YES 268If set to 269.Dq NO , 270the very early 271boot-time entropy file 272will not be loaded. 273See the entropy entries in 274.Xr rc.conf 5 . 275.It Va entropy_cache_name 276.Pq Dq /boot/entropy 277The name of the very early 278boot-time entropy cache file. 279.El 280.Sh OTHER SETTINGS 281Other settings that may be used in 282.Nm 283that have no default value: 284.Bl -tag -width bootfile -offset indent 285.It Va fdt_overlays 286Specifies a comma-delimited list of FDT overlays to apply. 287.Pa /boot/dtb/overlays 288is created by default for overlays to be placed in. 289.It Va kernels_autodetect 290If set to 291.Dq YES , 292attempt to auto-detect kernels installed in 293.Pa /boot . 294This is an option specific to the Lua-based loader. 295It is not available in the default Forth-based loader. 296.El 297.Sh FILES 298.Bl -tag -width /boot/defaults/loader.conf -compact 299.It Pa /boot/defaults/loader.conf 300default settings -- do not change this file. 301.It Pa /boot/loader.conf 302user defined settings. 303.It Pa /boot/loader.conf.local 304machine-specific settings for sites with a common loader.conf. 305.El 306.Sh SEE ALSO 307.Xr rc.conf 5 , 308.Xr boot 8 , 309.Xr loader 8 , 310.Xr loader.4th 8 311.Sh HISTORY 312The file 313.Nm 314first appeared in 315.Fx 3.2 . 316.Sh AUTHORS 317This manual page was written by 318.An Daniel C. Sobral Aq dcs@FreeBSD.org . 319.Sh BUGS 320The 321.Xr loader 8 322stops reading 323.Nm 324when it encounters a syntax error, so any options which are vital for 325booting a particular system (i.e.\& 326.Dq Va hw.ata.ata_dma Ns "=0" ) 327should precede any experimental additions to 328.Nm . 329
