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