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 November 26, 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 will be inserted and the boot will proceed immediately unless a key 98has already been pressed, which may be practically impossible. 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 332Comma- or space-separated list of consoles. 333.Dq comconsole 334selects serial console, 335.Dq vidconsole 336selects the video console, 337.Dq efi 338selects the EFI console, 339.Dq nullconsole 340selects a mute console 341(useful for systems with neither a video console nor a serial port), and 342.Dq spinconsole 343selects the video console which prevents any input and hides all output 344replacing it with 345.Dq spinning 346character (useful for embedded products and such). 347This setting is for the 348.Xr loader 8 349only and does not set the kernel output. 350.It Va screen.font 351Set font size for framebuffer mode. 352The default font size is selected based on screen resolution. 353Note that the terminal's size may vary. 354.It Va screen.textmode 355Value 356.Dq 0 357will trigger BIOS loader to switch to use VESA BIOS Extension (VBE) 358frame buffer mode for console. 359The same effect can be achieved by setting 360.Va vbe_max_resolution . 361.Pp 362Value 363.Dq 1 364will force BIOS loader to use VGA text mode. 365.Pp 366If 367.Va vbe_max_resolution 368is not set, the loader will try to set screen resolution based on EDID 369information. 370If EDID is not available, the default resolution is 800x600 (if available). 371.It Va screen.height 372.It Va screen.width 373.It Va screen.depth 374.Va screen.height , 375.Va screen.width , 376.Va screen.depth 377are set by loader when loader is using framebuffer mode to draw the screen. 378.It Va efi_max_resolution 379.It Va vbe_max_resolution 380Specify the maximum desired resolution for the EFI or VBE framebuffer console. 381The following values are accepted: 382.Bl -column "WidthxHeight" 383.It Sy Value Ta Sy Resolution 384.It 480p Ta 640x480 385.It 720p Ta 1280x720 386.It 1080p Ta 1920x1080 387.It 1440p Ta 2560x1440 388.It 2160p Ta 3840x2160 389.It 4k Ta 3840x2160 390.It 5k Ta 5120x2880 391.It Va Width Ns x Ns Va Height Ta Va Width Ns x Ns Va Height 392.El 393.It Va kernel 394.Pq Dq kernel 395.It Va kernels 396.Pq Dq kernel kernel.old 397Space or comma separated list of kernels to present in the boot menu. 398.It Va loader_conf_files 399.Pq Dq Pa /boot/loader.conf /boot/loader.conf.local 400.It Va loader_conf_dirs 401.Pq Dq Pa /boot/loader.conf.d 402.It Va splash_bmp_load 403.Pq Dq NO 404If set to 405.Dq YES , 406will load the splash screen module, making it possible to display a bmp image 407on the screen while booting. 408.It Va splash_pcx_load 409.Pq Dq NO 410If set to 411.Dq YES , 412will load the splash screen module, making it possible to display a pcx image 413on the screen while booting. 414.It Va vesa_load 415.Pq Dq NO 416If set to 417.Dq YES , 418the vesa module will be loaded, enabling bitmaps above VGA resolution to 419be displayed. 420.It Va beastie_disable 421If set to 422.Dq YES , 423the beastie boot menu will be skipped. 424.It Va loader_autoboot_show Pq Dq Li YES 425If set to 426.Dq NO , 427the autoboot menu will not be displayed 428.It Va loader_gfx 429If set to 430.Dq NO , 431the ASCII art version of the brand and logo will be used even if graphical 432versions are available. 433Additionally, the menu frame will be drawn with ASCII art as well. 434.It Va loader_logo Pq Dq Li orbbw 435Selects a desired logo in the beastie boot menu. 436Possible values are: 437.Dq Li orbbw , 438.Dq Li orb , 439.Dq Li fbsdbw , 440.Dq Li beastiebw , 441.Dq Li beastie , 442and 443.Dq Li none . 444.It Va loader_menu 445If set to 446.Dq NONE , 447the menu will not be displayed 448.It Va loader_color 449If set to 450.Dq NO , 451the beastie boot menu will be displayed without ANSI coloring. 452.It Va entropy_cache_load 453.Pq Dq YES 454If set to 455.Dq NO , 456the very early 457boot-time entropy file 458will not be loaded. 459See the entropy entries in 460.Xr rc.conf 5 . 461.It Va entropy_cache_name 462.Pq Dq /boot/entropy 463The name of the very early 464boot-time entropy cache file. 465.It Va cpu_microcode_load 466.Pq Dq NO 467If set to 468.Dq YES , 469the microcode update file specified by 470.Va cpu_microcode_name 471will be loaded and applied very early during boot. 472This provides functionality similar to 473.Xr cpucontrol 8 474but ensures that CPU features enabled by microcode updates can be 475used by the kernel. 476The update will be re-applied automatically when resuming from an 477ACPI sleep state. 478If the update file contains updates for multiple processor models, 479the kernel will search for and extract a matching update. 480Currently this setting is supported only on Intel 481.Dv i386 482and 483.Dv amd64 484processors. 485It has no effect on other processor types. 486.It Va cpu_microcode_name 487A path to a microcode update file. 488.El 489.Sh OTHER SETTINGS 490Other settings that may be used in 491.Nm 492that have no default value: 493.Bl -tag -width bootfile -offset indent 494.It Va fdt_overlays 495Specifies a comma-delimited list of FDT overlays to apply. 496.Pa /boot/dtb/overlays 497is created by default for overlays to be placed in. 498.It Va kernels_autodetect 499If set to 500.Dq YES , 501attempt to auto-detect kernels installed in 502.Pa /boot . 503This is an option specific to the Lua-based loader. 504It is not available in the default Forth-based loader. 505.El 506.Sh FILES 507.Bl -tag -width /boot/defaults/loader.conf -compact 508.It Pa /boot/defaults/loader.conf 509Default settings \(em do not change this file. 510.It Pa /boot/loader.conf 511User defined settings. 512.It Pa /boot/loader.conf.lua 513User defined settings written in lua. 514.It Pa /boot/loader.conf.d/*.conf 515User defined settings split in separate files. 516.It Pa /boot/loader.conf.d/*.lua 517User defined settings written in lua and split in separate files. 518.It Pa /boot/loader.conf.local 519Machine-specific settings for sites with a common loader.conf. Allow to override 520settings defined in other files. 521.El 522.Sh SEE ALSO 523.Xr kenv 1 , 524.Xr loader.conf.lua 5 , 525.Xr rc.conf 5 , 526.Xr boot 8 , 527.Xr cpucontrol 8 , 528.Xr loader 8 , 529.Xr loader.4th 8 530.Sh HISTORY 531The file 532.Nm 533first appeared in 534.Fx 3.2 . 535.Sh AUTHORS 536This manual page was written by 537.An Daniel C. Sobral Aq dcs@FreeBSD.org . 538.Sh BUGS 539The 540.Xr loader 8 541stops reading 542.Nm 543when it encounters a syntax error, so any options which are vital for 544booting a particular system (i.e., 545.Dq Va hw.ata.ata_dma Ns "=0" ) 546should precede any experimental additions to 547.Nm . 548
