share/man/man5/loader.conf.5

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