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