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.Dd February 9, 2025 25.Dt LOADER.CONF 5 26.Os 27.Sh NAME 28.Nm loader.conf 29.Nd "system bootstrap configuration information" 30.Sh DESCRIPTION 31The file 32.Nm 33contains descriptive information on bootstrapping the system. 34Through 35it you can specify the kernel to be booted, parameters to be passed to 36it, and additional modules to be loaded; and generally set all variables 37described in 38.Xr loader 8 . 39.Sh SYNTAX 40Though 41.Nm Ns 's 42format was defined explicitly to resemble 43.Xr rc.conf 5 , 44and can be sourced by 45.Xr sh 1 , 46some settings are treated in a special fashion. 47Also, the 48behavior of some settings is defined by the setting's suffix; 49the prefix identifies which module the setting controls. 50.Pp 51The general parsing rules are: 52.Bl -bullet 53.It 54Spaces and empty lines are ignored. 55.It 56A # sign will mark the remainder of the line as a comment. 57.It 58Only one setting can be present on each line. 59.El 60.Pp 61All settings have the following format: 62.Pp 63.Dl variable="value" 64.Pp 65Unless it belongs to one of the classes of settings that receive special 66treatment, a setting will set the value of a 67.Xr loader 8 68environment variable. 69The settings that receive special 70treatment are listed below. 71Settings beginning with 72.Qq * 73below define the modules to be loaded and 74may have any prefix; the prefix identifies a module. 75All such settings sharing a common 76prefix refer to the same module. 77.Bl -tag -width Ar 78.It Ar autoboot_delay 79Delay in seconds before automatically booting. 80A user with console access will be able to interrupt the 81.Ic autoboot 82process and escape into the interactive mode by pressing a key on 83the console during this delay. 84.Pp 85If set to 86.Dq Li NO , 87no 88.Ic autoboot 89is automatically attempted after processing 90.Pa /boot/loader.rc , 91though explicit 92.Ic autoboot Ns 's 93are processed normally, using a 10 second delay. 94.Pp 95If set to 96.Dq Li 0 , 97no delay is inserted, but any keys pressed while the kernel and modules are 98loaded will enter interactive mode. 99.Pp 100If set to 101.Dq Li -1 , 102no delay will be inserted and 103.Nm 104starts interactive mode only if 105.Ic autoboot 106has failed. 107In combination with the 108.Va beastie_disable 109option, this option prevents users with console access from being able 110to interrupt the 111.Ic autoboot 112process and escape to the loader prompt. 113To use the 114.Va autoboot_delay 115option in this manner, 116.Va beastie_disable 117must be set to 118.Dq Li YES . 119.It Ar boot_* 120See list in 121.Xr loader.efi 8 122since those flags apply to all boot loaders. 123.It Ar boot_verbose 124Set to "yes" to get the same effect as boot -v or booting verbose from the 125loader menu. 126.It Ar exec 127Immediately executes a 128.Xr loader 8 129command. 130This type of setting cannot be processed by programs other 131than 132.Xr loader 8 , 133so its use should be avoided. 134Multiple instances of it will be processed 135independently. 136.It Ar loader_conf_dirs 137Space separated list of directories to process for configuration files. 138The lua-based loader will process files with a 139.Dq .conf 140suffix that are placed in these directories. 141Files found here are processed after the ones listed in 142.Va loader_conf_files 143but before the ones found in 144.Va local_loader_conf_files . 145.It Ar loader_conf_files 146Defines additional configuration files to be processed right after the 147present file. 148.Ar loader_conf_files 149should be treated as write-only. 150One cannot depend on any value remaining in the loader environment or carried 151over into the kernel environment. 152.It Ar local_loader_conf_files 153Space separated list of additional configuration files to be processed at last, 154i.e., after 155.Va loader_conf_files 156and 157.Va loader_conf_dirs 158are processed. 159.It Ar product_vars 160When set, must be a space separated list of environment variable names to walk 161through to guess product information. 162The order matters as reading a config file override the previously defined 163values. 164Undefined variables are silently ignored. 165.Pp 166When product information can be guessed, for each product information found, 167append 168.Pa /boot/loader.conf.d/PRODUCT 169to 170.Ar loader_conf_dirs . 171It can be typically used as follow: 172.Bd -literal 173smbios.system.planar.maker="PLANAR_MAKER" 174smbios.system.planar.product="PLANAR_PRODUCT" 175smbios.system.product="PRODUCT" 176uboot.m_product="M_PRODUCT" 177product_vars="smbios.system.planar.maker smbios.system.planar.product smbios.system.product uboot.m_product" 178.Ed 179.Pp 180to read files found in the following directories, in that order: 181.Bl -bullet -compact 182.It 183.Pa /boot/loader.conf.d/PLANAR_MAKER 184.It 185.Pa /boot/loader.conf.d/PLANAR_PRODUCT 186.It 187.Pa /boot/loader.conf.d/PRODUCT 188.It 189.Pa /boot/loader.conf.d/M_PRODUCT 190.El 191.It Ar kernel 192Name of the kernel to be loaded. 193If no kernel name is set, no additional 194modules will be loaded. 195The name must be a subdirectory of 196.Pa /boot 197that contains a kernel. 198.It Ar kernel_options 199Flags to be passed to the kernel. 200.It Ar vfs.root.mountfrom 201Specify the root partition to mount. 202For example: 203.Pp 204.Dl vfs.root.mountfrom="ufs:/dev/da0s1a" 205.Pp 206.Xr loader 8 207automatically calculates the value of this tunable from 208.Pa /etc/fstab 209from the partition the kernel was loaded from. 210The calculated value might be calculated incorrectly when 211.Pa /etc/fstab 212is not available during 213.Xr loader 8 214startup (as during diskless booting from NFS), or if a different 215device is desired by the user. 216The preferred value can be set in 217.Pa /loader.conf . 218.Pp 219The value can also be overridden from the 220.Xr loader 8 221command line. 222This is useful for system recovery when 223.Pa /etc/fstab 224is damaged, lost, or read from the wrong partition. 225.It Ar password 226Protect boot menu with a password without interrupting 227.Ic autoboot 228process. 229The password should be in clear text format. 230If a password is set, boot menu will not appear until any key is pressed during 231countdown period specified by 232.Va autoboot_delay 233variable or 234.Ic autoboot 235process fails. 236In both cases user should provide specified password to be able to access boot 237menu. 238.It Ar bootlock_password 239Provides a password to be required by check-password before execution is 240allowed to continue. 241The password should be in clear text format. 242If a password is set, the user must provide specified password to boot. 243.It Ar verbose_loading 244If set to 245.Dq YES , 246module names will be displayed as they are loaded. 247.It Ar module_blacklist 248Blacklist of modules. 249Modules specified in the blacklist may not be loaded automatically with a 250.Ar *_load 251directive, but they may be loaded directly at the 252.Xr loader 8 253prompt. 254Blacklisted modules may still be loaded indirectly as dependencies of other 255modules. 256.It Ar *_load 257If set to 258.Dq YES , 259that module will be loaded. 260If no name is defined (see below), the 261module's name is taken to be the same as the prefix. 262.It Ar *_name 263Defines the name of the module. 264.It Ar *_type 265Defines the module's type. 266If none is given, it defaults to a kld module. 267.It Ar *_flags 268Flags and parameters to be passed to the module. 269.It Ar *_before 270Commands to be executed before the module is loaded. 271Use of this setting 272should be avoided. 273.It Ar *_after 274Commands to be executed after the module is loaded. 275Use of this setting 276should be avoided. 277.It Ar *_error 278Commands to be executed if the loading of a module fails. 279Except for the 280special value 281.Dq abort , 282which aborts the bootstrap process, use of this setting should be avoided. 283.El 284.Pp 285.Em WARNING : 286developers should never use these suffixes for any kernel environment 287variables (tunables) or conflicts will result. 288.Sh DEFAULT SETTINGS 289Most of 290.Nm Ns 's 291default settings can be ignored. 292The few of them which are important 293or useful are: 294.Bl -tag -width bootfile -offset indent 295.It Va local_loader_conf_files 296.Pq Dq /boot/loader.conf.local 297Ensure 298.Va loader.conf.local 299can always be used to override settings from files found in 300.Va loader_conf_files 301and 302.Va loader_conf_dirs . 303.It Va bitmap_load 304.Pq Dq NO 305If set to 306.Dq YES , 307a bitmap will be loaded to be displayed on screen while booting. 308.It Va bitmap_name 309.Pq Dq Pa /boot/splash.bmp 310Name of the bitmap to be loaded. 311Any other name can be used. 312.It Va comconsole_speed 313.Dq ( 115200 314or the value of the 315.Va BOOT_COMCONSOLE_SPEED 316variable when 317.Xr loader 8 318was compiled). 319Sets the speed of the serial console. 320If the previous boot loader stage specified that a serial console 321is in use then the default speed is determined from the current 322serial port speed setting. 323.It Va console 324.Pq Dq vidconsole 325.Dq comconsole 326selects serial console, 327.Dq vidconsole 328selects the video console, 329.Dq efi 330selects the EFI console, 331.Dq nullconsole 332selects a mute console 333(useful for systems with neither a video console nor a serial port), and 334.Dq spinconsole 335selects the video console which prevents any input and hides all output 336replacing it with 337.Dq spinning 338character (useful for embedded products and such). 339.It Va screen.font 340Set font size for framebuffer mode. 341The default font size is selected based on screen resolution. 342Note that the terminal's size may vary. 343.It Va screen.textmode 344Value 345.Dq 0 346will trigger BIOS loader to switch to use VESA BIOS Extension (VBE) 347frame buffer mode for console. 348The same effect can be achieved by setting 349.Va vbe_max_resolution . 350.Pp 351Value 352.Dq 1 353will force BIOS loader to use VGA text mode. 354.Pp 355If 356.Va vbe_max_resolution 357is not set, the loader will try to set screen resolution based on EDID 358information. 359If EDID is not available, the default resolution is 800x600 (if available). 360.It Va screen.height 361.It Va screen.width 362.It Va screen.depth 363.Va screen.height , 364.Va screen.width , 365.Va screen.depth 366are set by loader when loader is using framebuffer mode to draw the screen. 367.It Va efi_max_resolution 368.It Va vbe_max_resolution 369Specify the maximum desired resolution for the EFI or VBE framebuffer console. 370The following values are accepted: 371.Bl -column "WidthxHeight" 372.It Sy Value Ta Sy Resolution 373.It 480p Ta 640x480 374.It 720p Ta 1280x720 375.It 1080p Ta 1920x1080 376.It 1440p Ta 2560x1440 377.It 2160p Ta 3840x2160 378.It 4k Ta 3840x2160 379.It 5k Ta 5120x2880 380.It Va Width Ns x Ns Va Height Ta Va Width Ns x Ns Va Height 381.El 382.It Va kernel 383.Pq Dq kernel 384.It Va kernels 385.Pq Dq kernel kernel.old 386Space or comma separated list of kernels to present in the boot menu. 387.It Va loader_conf_files 388.Pq Dq Pa /boot/loader.conf /boot/loader.conf.local 389.It Va loader_conf_dirs 390.Pq Dq Pa /boot/loader.conf.d 391.It Va splash_bmp_load 392.Pq Dq NO 393If set to 394.Dq YES , 395will load the splash screen module, making it possible to display a bmp image 396on the screen while booting. 397.It Va splash_pcx_load 398.Pq Dq NO 399If set to 400.Dq YES , 401will load the splash screen module, making it possible to display a pcx image 402on the screen while booting. 403.It Va vesa_load 404.Pq Dq NO 405If set to 406.Dq YES , 407the vesa module will be loaded, enabling bitmaps above VGA resolution to 408be displayed. 409.It Va beastie_disable 410If set to 411.Dq YES , 412the beastie boot menu will be skipped. 413.It Va loader_logo Pq Dq Li orbbw 414Selects a desired logo in the beastie boot menu. 415Possible values are: 416.Dq Li orbbw , 417.Dq Li orb , 418.Dq Li fbsdbw , 419.Dq Li beastiebw , 420.Dq Li beastie , 421and 422.Dq Li none . 423.It Va loader_color 424If set to 425.Dq NO , 426the beastie boot menu will be displayed without ANSI coloring. 427.It Va entropy_cache_load 428.Pq Dq YES 429If set to 430.Dq NO , 431the very early 432boot-time entropy file 433will not be loaded. 434See the entropy entries in 435.Xr rc.conf 5 . 436.It Va entropy_cache_name 437.Pq Dq /boot/entropy 438The name of the very early 439boot-time entropy cache file. 440.It Va cpu_microcode_load 441.Pq Dq NO 442If set to 443.Dq YES , 444the microcode update file specified by 445.Va cpu_microcode_name 446will be loaded and applied very early during boot. 447This provides functionality similar to 448.Xr cpucontrol 8 449but ensures that CPU features enabled by microcode updates can be 450used by the kernel. 451The update will be re-applied automatically when resuming from an 452ACPI sleep state. 453If the update file contains updates for multiple processor models, 454the kernel will search for and extract a matching update. 455Currently this setting is supported only on Intel 456.Dv i386 457and 458.Dv amd64 459processors. 460It has no effect on other processor types. 461.It Va cpu_microcode_name 462A path to a microcode update file. 463.El 464.Sh OTHER SETTINGS 465Other settings that may be used in 466.Nm 467that have no default value: 468.Bl -tag -width bootfile -offset indent 469.It Va fdt_overlays 470Specifies a comma-delimited list of FDT overlays to apply. 471.Pa /boot/dtb/overlays 472is created by default for overlays to be placed in. 473.It Va kernels_autodetect 474If set to 475.Dq YES , 476attempt to auto-detect kernels installed in 477.Pa /boot . 478This is an option specific to the Lua-based loader. 479It is not available in the default Forth-based loader. 480.El 481.Sh FILES 482.Bl -tag -width /boot/defaults/loader.conf -compact 483.It Pa /boot/defaults/loader.conf 484Default settings \(em do not change this file. 485.It Pa /boot/loader.conf 486User defined settings. 487.It Pa /boot/loader.conf.lua 488User defined settings written in lua. 489.It Pa /boot/loader.conf.d/*.conf 490User defined settings split in separate files. 491.It Pa /boot/loader.conf.d/*.lua 492User defined settings written in lua and split in separate files. 493.It Pa /boot/loader.conf.local 494Machine-specific settings for sites with a common loader.conf. Allow to override 495settings defined in other files. 496.El 497.Sh SEE ALSO 498.Xr kenv 1 , 499.Xr loader.conf.lua 5 , 500.Xr rc.conf 5 , 501.Xr boot 8 , 502.Xr cpucontrol 8 , 503.Xr loader 8 , 504.Xr loader.4th 8 505.Sh HISTORY 506The file 507.Nm 508first appeared in 509.Fx 3.2 . 510.Sh AUTHORS 511This manual page was written by 512.An Daniel C. Sobral Aq dcs@FreeBSD.org . 513.Sh BUGS 514The 515.Xr loader 8 516stops reading 517.Nm 518when it encounters a syntax error, so any options which are vital for 519booting a particular system (i.e., 520.Dq Va hw.ata.ata_dma Ns "=0" ) 521should precede any experimental additions to 522.Nm . 523
