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.\" 25.\" $FreeBSD: src/sys/boot/forth/loader.conf.5,v 1.18 2002/08/27 01:02:56 trhodes Exp $ 26.\" 27.Dd October 29, 2020 28.Dt LOADER.CONF 5 29.Os 30.Sh NAME 31.Nm loader.conf 32.Nd system bootstrap configuration information 33.Sh DESCRIPTION 34The file 35.Nm 36contains descriptive information on bootstrapping the system. 37Through it you can specify the kernel to be booted, 38parameters to be passed to it, 39and additional kernel modules to be loaded; 40and generally set all variables described in 41.Xr loader 8 . 42.Pp 43A file 44.Pa dloader.rc 45must contain the following lines for 46.Nm 47to be automatically processed: 48.Pp 49.Dl include defaults/loader.conf 50.Dl optinclude loader.conf 51.Dl optinclude loader.conf.local 52.Pp 53If no 54.Pa /boot/dloader.rc 55exists at installworld time, one with the above lines will be installed. 56.Sh SYNTAX 57Though 58.Nm Ns 's 59format was defined explicitly to resemble 60.Xr rc.conf 5 , 61and can be sourced by 62.Xr sh 1 , 63some settings are treated in a special fashion. 64Also, the behavior of some settings is defined by the setting's suffix; 65the prefix identifies which module the setting controls. 66.Pp 67The general parsing rules are: 68.Bl -bullet 69.It 70Spaces and empty lines are ignored. 71.It 72A 73.Ql # 74sign will mark the remainder of the line as a comment. 75.It 76Only one setting can be present on each line. 77.El 78.Pp 79All settings have the following format: 80.Pp 81.Dl variable="value" 82.Pp 83This assigns value to a local variable. 84If variable is in a list of known kernel environment variables or 85is a kernel tunable, 86it is also assigned to the kernel environment variable of the given name. 87.Pp 88The settings that receive special treatment are listed below. 89Settings beginning with 90.Aq Ar module 91below define the kernel modules to be loaded. 92All such settings sharing a common 93prefix refer to the same module. 94.Bl -tag -width indent 95.It Ar kernel 96Name of the kernel to be loaded. 97If no kernel name is set, no additional 98modules will be loaded. 99.It Ar kernel_options 100Flags to be passed to the kernel (see 101.Xr boot 8 ) . 102.It Ar verbose_loading 103If set to 104.Dq YES , 105module names will be displayed as they are loaded. 106.It Ao Ar module Ac Ns Ar _load 107If set to 108.Dq YES , 109that kernel module will be loaded. 110If no 111.Ao Ar module Ac Ns Ar _name 112is defined (see below), the 113module's name is taken to be 114.Aq Ar module . 115Only modules necessary for mounting the root file system should be loaded from 116.Nm 117due to memory limitations in the early boot phase. 118Other modules can be loaded later via similar entries in 119.Xr rc.conf 5 . 120.It Ao Ar module Ac Ns Ar _name 121Defines the name of the module. 122.It Ao Ar module Ac Ns Ar _type 123Defines the module's type. 124If none is given, it defaults to a 125.Xr kld 4 126module. 127.It Ao Ar module Ac Ns Ar _flags 128Flags and parameters to be passed to the module. 129.It Ao Ar module Ac Ns Ar _before 130Commands to be executed before the module is loaded. 131Use of this setting 132should be avoided. 133.It Ao Ar module Ac Ns Ar _after 134Commands to be executed after the module is loaded. 135Use of this setting 136should be avoided. 137.It Ao Ar module Ac Ns Ar _error 138Commands to be executed if the loading of a module fails. 139Except for the 140special value 141.Dq abort , 142which aborts the bootstrap process, use of this setting should be avoided. 143.El 144.Sh DEFAULT SETTINGS 145See 146.Pa /boot/defaults/loader.conf 147for 148.Nm Ns 's 149default settings. 150The few of them which are important 151or useful are: 152.Bl -tag -width indent 153.It Va bitmap_load 154.Pq Dq NO 155If set to 156.Dq YES , 157a bitmap will be loaded to be displayed on screen while booting. 158.It Va bitmap_name 159.Pq Dq splash.bmp 160Name of the bitmap to be loaded. 161Any other name can be used. 162.It Va boot_verbose 163.Pq Dq NO 164Set to 165.Dq YES 166to enable verbose booting. 167.It Va console 168.Pq Dq vidconsole 169.Dq comconsole 170selects serial console, 171.Dq vidconsole 172selects the video console, and 173.Dq nullconsole 174selects a mute console 175(useful for systems with neither a video console nor a serial port). 176.Pp 177When using a comconsole the kernel defaults to allowing a console on sio0. 178To change this to sio1 you must specify 179.Va sio0.flags=0 180and 181.Va sio1.flags=0x10 182in addition to setting the console to the comconsole. 183You can also set the baud rate with (for example) 184.Va sio1.baud=115200 185or simply inherit the baud set in the boot code. 186Normally these must be set if you want to use a stock kernel in a 187IPMI environment. 188When setting the serial console you must specify the serial port 189with (for example) 190.Va sio1.port=0x3e8 . 191Typically sio0 is on 0x3f8 and sio1 is on 0x2f8, but IPMI consoles 192on sio1 are often on 0x3e8 (instead of sio2), which can be confusing. 193Be sure to specify the correct port 194if you want early kernel boot messages to work. 195If you do not specify the port the console will still operate on 196the serial port but only after the kernel has started init. 197.Pp 198Some IPMI environments do not enable sio1 during the BIOS boot, 199which can cause the loader to get confused and not pass RB_SERIAL 200to the kernel. 201Setting console=comconsole in this situation also does not work because 202then the loader is inacessible. Instead, set the sioX fields as shown 203above and also add 204.Va set boot_serial="YES" 205to cause the kernel to use the serial port without also forcing the 206boot loader to use the serial port. 207.Pp 208In contrast to the above, if you wish to place your serial console 209on a late-configuring serial port (such as one from a PCIe card), 210that serial port will not be available to the loader or for half 211the boot and it is probably best to leave 212.Va boot_serial unset . 213In 214this situation, syscons may have already taken the console, so 215you need to override it using (for example) 216.Va sio4.flags=0x30 instead of 0x10. 217.Pp 218The boot1/boot2 code uses BIOS calls to read and write the screen but also 219mirrors output to and monitors COM1 @ 9600. 220In an IPMI environment you do not usually have to adjust the boot code 221at all, instead using the IPMI feature to redirect the video output. 222In non-IPMI setups if you want the boot code to be available on 223COM2 at 57600 baud instead of COM1, for example, you must set the variables 224.Va BOOT_COMCONSOLE_PORT=0x2f8 225and 226.Va BOOT_COMCONSOLE_SPEED=57600 227in 228.Pa /etc/make.conf 229and recompile and install the boot code at 230.Pa /usr/src/stand/boot , 231then install the bootcode to the partition via 232.Xr disklabel 8 . 233.Pp 234Note that in comconsole mode the kernel will pick up the baud rate 235from the boot loader, so no kernel recompile is needed. 236.It Va kernel 237.Pq Dq kernel . 238.It Va loader_plain 239.Pq Dq NO 240Unlike in the past, the loader defaults to displaying Fred, the official 241.Dx 242mascot, in color when the boot menu appears, unless 243.Pa console 244is set to 245.Dq comconsole 246in 247.Pa loader.conf 248or in the environment. If set to 249.Dq YES , 250Fred will always be displayed in monochrome. 251.It Va fred_is_red 252.Pq Dq NO 253Under color mode, Fred is depicted as a blue dragonfly with cyan wings 254by default. If set to 255.Dq YES , 256Fred will be shown as a red dragonfly with red wings instead. 257.It Va fred_disable 258.Pq Dq NO 259Fred is displayed with the menu by default. If set to 260.Dq YES , 261Fred will not be shown. The area will simply be blank. 262.It Va fred_on_left 263.Pq Dq NO 264If set to 265.Dq YES , 266Fred will be displayed on the left side of the menu rather than the right side. 267.It Va fred_separated 268.Pq Dq NO 269If set to 270.Dq YES , 271a line will be drawn between Fred and the menu block. 272.It Va splash_bmp_load 273.Pq Dq NO 274If set to 275.Dq YES , 276will load the splash screen module, making it possible to display a bmp image 277on the screen while booting. 278.It Va splash_pcx_load 279.Pq Dq NO 280If set to 281.Dq YES , 282will load the splash screen module, making it possible to display a pcx image 283on the screen while booting. 284.El 285.Sh IPMI 286Generally speaking machines with IPMI capabilities are capable of 287redirecting the BIOS POST to a fake serial port controlled by the BMC. 288It is then possible to use 289.Xr ipmitool 1 290from 291.Xr dports 7 292to access the console. 293.Dx 294kernels adjust the video mode in a way that the BMC cannot usually 295redirect, so your best bet is to set the boot loader AND the kernel up to 296use a serial port via the 297.Va console=comconsole 298feature described above. 299Often the IPMI controller, called the BMC, is not sitting on COM1 so 300.Dx Ap s 301default console parameters and baud rate will not work. 302.Sh FILES 303.Bl -tag -width ".Pa /boot/defaults/dloader.menu" -compact 304.It Pa /boot/defaults/dloader.menu 305default settings for menu setup -- do not change this file. 306.It Pa /boot/defaults/loader.conf 307default settings -- do not change this file. 308.It Pa /boot/dloader.menu 309defines the commands used by 310.Nm loader 311to setup menus. 312.It Pa /boot/loader.conf 313user defined settings. 314.It Pa /boot/loader.conf.local 315machine-specific settings for sites with a common loader.conf. 316.It Pa /boot/dloader.rc 317contains the instructions to automatically process. 318.El 319.Sh SEE ALSO 320.Xr boot 8 , 321.Xr loader 8 322.Sh HISTORY 323The file 324.Nm 325first appeared in 326.Fx 3.2 . 327.Sh AUTHORS 328This manual page was written by 329.An Daniel C. Sobral Aq Mt dcs@FreeBSD.org . 330
