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