stand/defaults/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$
  26 .Dd October 8, 2021
  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
  37 it you can specify the kernel to be booted, parameters to be passed to
  38 it, and additional modules to be loaded; and generally set all variables
  39 described in
  40 .Xr loader 8 .
  41 .Pp
  42 .Sh SYNTAX
  43 Though
  44 .Nm Ns 's
  45 format was defined explicitly to resemble
  46 .Xr rc.conf 5 ,
  47 and can be sourced by
  48 .Xr sh 1 ,
  49 some settings are treated in a special fashion.
  50 Also, the
  51 behavior of some settings is defined by the setting's suffix;
  52 the prefix identifies which module the setting controls.
  53 .Pp
  54 The general parsing rules are:
  55 .Bl -bullet
  56 .It
  57 Spaces and empty lines are ignored.
  58 .It
  59 A # sign will mark the remainder of the line as a comment.
  60 .It
  61 Only one setting can be present on each line.
  62 .El
  63 .Pp
  64 All settings have the following format:
  65 .Pp
  66 .Dl variable="value"
  67 .Pp
  68 Unless it belongs to one of the classes of settings that receive special
  69 treatment, a setting will set the value of a
  70 .Xr loader 8
  71 environment variable.
  72 The settings that receive special
  73 treatment are listed below.
  74 Settings beginning with
  75 .Qq *
  76 below define the modules to be loaded and
  77 may have any prefix; the prefix identifies a module.
  78 All such settings sharing a common
  79 prefix refer to the same module.
  80 .Bl -tag -width Ar
  81 .It Ar autoboot_delay
  82 Delay in seconds before automatically booting.
  83 A user with console access will be able to interrupt the
  84 .Ic autoboot
  85 process and escape into the interactive mode by pressing a key on
  86 the console during this delay.
  87 .Pp
  88 If set to
  89 .Dq Li NO ,
  90 no
  91 .Ic autoboot
  92 is automatically attempted after processing
  93 .Pa /boot/loader.rc ,
  94 though explicit
  95 .Ic autoboot Ns 's
  96 are processed normally, using a 10 second delay.
  97 .Pp
  98 If set to
  99 .Dq Li 0 ,
 100 no delay is inserted, but any keys pressed while the kernel and modules are
 101 loaded will enter interactive mode.
 102 .Pp
 103 If set to
 104 .Dq Li -1 ,
 105 no delay will be inserted and
 106 .Nm
 107 starts interactive mode only if
 108 .Ic autoboot
 109 has failed.
 110 In combination with the
 111 .Va beastie_disable
 112 option, this option prevents users with console access from being able
 113 to interrupt the
 114 .Ic autoboot
 115 process and escape to the loader prompt.
 116 To use the
 117 .Va autoboot_delay
 118 option in this manner,
 119 .Va beastie_disable
 120 must be set to
 121 .Dq Li YES .
 122 .It Ar exec
 123 Immediately executes a
 124 .Xr loader 8
 125 command.
 126 This type of setting cannot be processed by programs other
 127 than
 128 .Xr loader 8 ,
 129 so its use should be avoided.
 130 Multiple instances of it will be processed
 131 independently.
 132 .It Ar loader_conf_dirs
 133 Space separated list of directories to process for configuration files.
 134 The lua-based loader will process files with a
 135 .Dq .conf
 136 suffix that are placed in these directories.
 137 .It Ar loader_conf_files
 138 Defines additional configuration files to be processed right after the
 139 present file.
 140 .Ar loader_conf_files
 141 should be treated as write-only.
 142 One cannot depend on any value remaining in the loader environment or carried
 143 over into the kernel environment.
 144 .It Ar kernel
 145 Name of the kernel to be loaded.
 146 If no kernel name is set, no additional
 147 modules will be loaded.
 148 The name must be a subdirectory of
 149 .Pa /boot
 150 that contains a kernel.
 151 .It Ar kernel_options
 152 Flags to be passed to the kernel.
 153 .It Ar vfs.root.mountfrom
 154 Specify the root partition to mount.
 155 For example:
 156 .Pp
 157 .Dl vfs.root.mountfrom="ufs:/dev/da0s1a"
 158 .Pp
 159 .Xr loader 8
 160 automatically calculates the value of this tunable from
 161 .Pa /etc/fstab
 162 from the partition the kernel was loaded from.
 163 The calculated value might be calculated incorrectly when
 164 .Pa /etc/fstab
 165 is not available during
 166 .Xr loader 8
 167 startup (as during diskless booting from NFS), or if a different
 168 device is desired by the user.
 169 The preferred value can be set in
 170 .Pa /loader.conf .
 171 .Pp
 172 The value can also be overridden from the
 173 .Xr loader 8
 174 command line.
 175 This is useful for system recovery when
 176 .Pa /etc/fstab
 177 is damaged, lost, or read from the wrong partition.
 178 .It Ar password
 179 Protect boot menu with a password without interrupting
 180 .Ic autoboot
 181 process.
 182 The password should be in clear text format.
 183 If a password is set, boot menu will not appear until any key is pressed during
 184 countdown period specified by
 185 .Va autoboot_delay
 186 variable or
 187 .Ic autoboot
 188 process fails.
 189 In both cases user should provide specified password to be able to access boot
 190 menu.
 191 .It Ar bootlock_password
 192 Provides a password to be required by check-password before execution is
 193 allowed to continue.
 194 The password should be in clear text format.
 195 If a password is set, the user must provide specified password to boot.
 196 .It Ar verbose_loading
 197 If set to
 198 .Dq YES ,
 199 module names will be displayed as they are loaded.
 200 .It Ar module_blacklist
 201 Blacklist of modules.
 202 Modules specified in the blacklist may not be loaded automatically with a
 203 .Ar *_load
 204 directive, but they may be loaded directly at the
 205 .Xr loader 8
 206 prompt.
 207 Blacklisted modules may still be loaded indirectly as dependencies of other
 208 modules.
 209 .It Ar *_load
 210 If set to
 211 .Dq YES ,
 212 that module will be loaded.
 213 If no name is defined (see below), the
 214 module's name is taken to be the same as the prefix.
 215 .It Ar *_name
 216 Defines the name of the module.
 217 .It Ar *_type
 218 Defines the module's type.
 219 If none is given, it defaults to a kld module.
 220 .It Ar *_flags
 221 Flags and parameters to be passed to the module.
 222 .It Ar *_before
 223 Commands to be executed before the module is loaded.
 224 Use of this setting
 225 should be avoided.
 226 .It Ar *_after
 227 Commands to be executed after the module is loaded.
 228 Use of this setting
 229 should be avoided.
 230 .It Ar *_error
 231 Commands to be executed if the loading of a module fails.
 232 Except for the
 233 special value
 234 .Dq abort ,
 235 which aborts the bootstrap process, use of this setting should be avoided.
 236 .El
 237 .Pp
 238 .Em WARNING:
 239 developers should never use these suffixes for any kernel environment
 240 variables (tunables) or conflicts will result.
 241 .Sh DEFAULT SETTINGS
 242 Most of
 243 .Nm Ns 's
 244 default settings can be ignored.
 245 The few of them which are important
 246 or useful are:
 247 .Bl -tag -width bootfile -offset indent
 248 .It Va bitmap_load
 249 .Pq Dq NO
 250 If set to
 251 .Dq YES ,
 252 a bitmap will be loaded to be displayed on screen while booting.
 253 .It Va bitmap_name
 254 .Pq Dq Pa /boot/splash.bmp
 255 Name of the bitmap to be loaded.
 256 Any other name can be used.
 257 .It Va comconsole_speed
 258 .Dq ( 9600
 259 or the value of the
 260 .Va BOOT_COMCONSOLE_SPEED
 261 variable when
 262 .Xr loader 8
 263 was compiled).
 264 Sets the speed of the serial console.
 265 If the previous boot loader stage specified that a serial console
 266 is in use then the default speed is determined from the current
 267 serial port speed setting.
 268 .It Va console
 269 .Pq Dq vidconsole
 270 .Dq comconsole
 271 selects serial console,
 272 .Dq vidconsole
 273 selects the video console,
 274 .Dq efi
 275 selects the EFI console,
 276 .Dq nullconsole
 277 selects a mute console
 278 (useful for systems with neither a video console nor a serial port), and
 279 .Dq spinconsole
 280 selects the video console which prevents any input and hides all output
 281 replacing it with
 282 .Dq spinning
 283 character (useful for embedded products and such).
 284 .It Va efi_max_resolution
 285 Specify the maximum desired resolution for the EFI console.
 286 The following values are accepted:
 287 .Bl -column "WidthxHeight"
 288 .It Sy Value Ta Sy Resolution
 289 .It 480p Ta 640x480
 290 .It 720p Ta 1280x720
 291 .It 1080p Ta 1920x1080
 292 .It 2160p Ta 3840x2160
 293 .It 4k Ta 3840x2160
 294 .It 5k Ta 5120x2880
 295 .It Va Width Ns x Ns Va Height Ta Va Width Ns x Ns Va Height
 296 .El
 297 .It Va kernel
 298 .Pq Dq kernel
 299 .It Va kernels
 300 .Pq Dq kernel kernel.old
 301 Space or comma separated list of kernels to present in the boot menu.
 302 .It Va loader_conf_files
 303 .Pq Dq Pa /boot/loader.conf /boot/loader.conf.local
 304 .It Va loader_conf_dirs
 305 .Pq Dq Pa /boot/loader.conf.d
 306 .It Va splash_bmp_load
 307 .Pq Dq NO
 308 If set to
 309 .Dq YES ,
 310 will load the splash screen module, making it possible to display a bmp image
 311 on the screen while booting.
 312 .It Va splash_pcx_load
 313 .Pq Dq NO
 314 If set to
 315 .Dq YES ,
 316 will load the splash screen module, making it possible to display a pcx image
 317 on the screen while booting.
 318 .It Va vesa_load
 319 .Pq Dq NO
 320 If set to
 321 .Dq YES ,
 322 the vesa module will be loaded, enabling bitmaps above VGA resolution to
 323 be displayed.
 324 .It Va beastie_disable
 325 If set to
 326 .Dq YES ,
 327 the beastie boot menu will be skipped.
 328 .It Va loader_logo Pq Dq Li orbbw
 329 Selects a desired logo in the beastie boot menu.
 330 Possible values are:
 331 .Dq Li orbbw ,
 332 .Dq Li orb ,
 333 .Dq Li fbsdbw ,
 334 .Dq Li beastiebw ,
 335 .Dq Li beastie ,
 336 and
 337 .Dq Li none .
 338 .It Va loader_color
 339 If set to
 340 .Dq NO ,
 341 the beastie boot menu will be displayed without ANSI coloring.
 342 .It Va entropy_cache_load
 343 .Pq Dq YES
 344 If set to
 345 .Dq NO ,
 346 the very early
 347 boot-time entropy file
 348 will not be loaded.
 349 See the entropy entries in
 350 .Xr rc.conf 5 .
 351 .It Va entropy_cache_name
 352 .Pq Dq /boot/entropy
 353 The name of the very early
 354 boot-time entropy cache file.
 355 .It Va cpu_microcode_load
 356 .Pq Dq NO
 357 If set to
 358 .Dq YES ,
 359 the microcode update file specified by
 360 .Va cpu_microcode_name
 361 will be loaded and applied very early during boot.
 362 This provides functionality similar to
 363 .Xr cpucontrol 8
 364 but ensures that CPU features enabled by microcode updates can be
 365 used by the kernel.
 366 The update will be re-applied automatically when resuming from an
 367 ACPI sleep state.
 368 If the update file contains updates for multiple processor models,
 369 the kernel will search for and extract a matching update.
 370 Currently this setting is supported only on Intel
 371 .Dv i386
 372 and
 373 .Dv amd64
 374 processors.
 375 It has no effect on other processor types.
 376 .It Va cpu_microcode_name
 377 A path to a microcode update file.
 378 .El
 379 .Sh OTHER SETTINGS
 380 Other settings that may be used in
 381 .Nm
 382 that have no default value:
 383 .Bl -tag -width bootfile -offset indent
 384 .It Va fdt_overlays
 385 Specifies a comma-delimited list of FDT overlays to apply.
 386 .Pa /boot/dtb/overlays
 387 is created by default for overlays to be placed in.
 388 .It Va kernels_autodetect
 389 If set to
 390 .Dq YES ,
 391 attempt to auto-detect kernels installed in
 392 .Pa /boot .
 393 This is an option specific to the Lua-based loader.
 394 It is not available in the default Forth-based loader.
 395 .El
 396 .Sh FILES
 397 .Bl -tag -width /boot/defaults/loader.conf -compact
 398 .It Pa /boot/defaults/loader.conf
 399 default settings -- do not change this file.
 400 .It Pa /boot/loader.conf
 401 user defined settings.
 402 .It Pa /boot/loader.conf.local
 403 machine-specific settings for sites with a common loader.conf.
 404 .El
 405 .Sh SEE ALSO
 406 .Xr rc.conf 5 ,
 407 .Xr boot 8 ,
 408 .Xr cpucontrol 8 ,
 409 .Xr loader 8 ,
 410 .Xr loader.4th 8
 411 .Sh HISTORY
 412 The file
 413 .Nm
 414 first appeared in
 415 .Fx 3.2 .
 416 .Sh AUTHORS
 417 This manual page was written by
 418 .An Daniel C. Sobral Aq dcs@FreeBSD.org .
 419 .Sh BUGS
 420 The
 421 .Xr loader 8
 422 stops reading
 423 .Nm
 424 when it encounters a syntax error, so any options which are vital for
 425 booting a particular system (i.e.\&
 426 .Dq Va hw.ata.ata_dma Ns "=0" )
 427 should precede any experimental additions to
 428 .Nm .