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