home | help 
LOADER.CONF(5)		       File Formats Manual		  LOADER.CONF(5)

NAME
     loader.conf -- system bootstrap configuration information

DESCRIPTION
     The  file loader.conf contains descriptive information on bootstrapping the
     system.  Through it you can specify the kernel to be booted, parameters  to
     be passed to it, and additional modules to be loaded; and generally set all
     variables described in loader(8).

SYNTAX
     Though  loader.conf's format was defined explicitly to resemble rc.conf(5),
     and can be sourced by sh(1), some settings are treated in a  special  fash-
     ion.   Also, the behavior of some settings is defined by the setting's suf-
     fix; the prefix identifies which module the setting controls.

     The general parsing rules are:

     *	 Spaces and empty lines are ignored.

     *	 A # sign will mark the remainder of the line as a comment.

     *	 Only one setting can be present on each line.

     All settings have the following format:

	   variable="value"

     Unless it belongs to one of the classes of settings  that	receive  special
     treatment,  a  setting  will set the value of a loader(8) environment vari-
     able.  The settings that receive special treatment are listed below.   Set-
     tings beginning with "*" below define the modules to be loaded and may have
     any  prefix;  the	prefix identifies a module.  All such settings sharing a
     common prefix refer to the same module.

     exec	   Immediately executes a loader(8) command.  This type of  set-
		   ting cannot be processed by programs other than loader(8), so
		   its	use should be avoided.	Multiple instances of it will be
		   processed independently.

     loader_conf_dirs
		   Space separated list of directories to process for configura-
		   tion files.	The lua-based loader will process files  with  a
		   ".conf" suffix that are placed in these directories.

     loader_conf_files
		   Defines  additional configuration files to be processed right
		   after the present file.  loader_conf_files should be  treated
		   as  write-only.   One cannot depend on any value remaining in
		   the loader environment or carried over into the kernel  envi-
		   ronment.

     kernel	   Name  of  the kernel to be loaded.  If no kernel name is set,
		   no additional modules will be loaded.  The  name  must  be  a
		   subdirectory of /boot that contains a kernel.

     kernel_options
		   Flags to be passed to the kernel.

     vfs.root.mountfrom
		   Specify the root partition to mount.  For example:

			 vfs.root.mountfrom="ufs:/dev/da0s1a"

		   loader(8)  automatically calculates the value of this tunable
		   from /etc/fstab from the  partition	the  kernel  was  loaded
		   from.   The	calculated value might be calculated incorrectly
		   when /etc/fstab is not available during loader(8) startup (as
		   during diskless booting from NFS), or if a  different  device
		   is  desired	by  the user.  The preferred value can be set in
		   /loader.conf.

		   The value can also be overridden from the  loader(8)  command
		   line.   This is useful for system recovery when /etc/fstab is
		   damaged, lost, or read from the wrong partition.

     password	   Protect  boot  menu	with  a  password  without  interrupting
		   autoboot  process.  The password should be in clear text for-
		   mat.  If a password is set, boot menu will not  appear  until
		   any	key  is  pressed  during  countdown  period specified by
		   autoboot_delay variable or autoboot process fails.	In  both
		   cases  user	should	provide specified password to be able to
		   access boot menu.

     bootlock_password
		   Provides a password to be required by  check-password  before
		   execution  is allowed to continue.  The password should be in
		   clear text format.  If a password is set, the user must  pro-
		   vide specified password to boot.

     verbose_loading
		   If  set  to "YES", module names will be displayed as they are
		   loaded.

     module_blacklist
		   Blacklist of modules.  Modules specified in the blacklist may
		   not be loaded automatically with a *_load directive, but they
		   may be loaded directly at the loader(8) prompt.   Blacklisted
		   modules  may  still	be  loaded indirectly as dependencies of
		   other modules.

     *_load	   If set to "YES", that module will be loaded.  If no	name  is
		   defined  (see  below),  the	module's name is taken to be the
		   same as the prefix.

     *_name	   Defines the name of the module.

     *_type	   Defines the module's type.  If none is given, it defaults  to
		   a kld module.

     *_flags	   Flags and parameters to be passed to the module.

     *_before	   Commands  to be executed before the module is loaded.  Use of
		   this setting should be avoided.

     *_after	   Commands to be executed after the module is loaded.	 Use  of
		   this setting should be avoided.

     *_error	   Commands  to  be  executed  if the loading of a module fails.
		   Except for the special value "abort", which aborts the  boot-
		   strap process, use of this setting should be avoided.

     WARNING: developers should never use these suffixes for any kernel environ-
     ment variables (tunables) or conflicts will result.

DEFAULT SETTINGS
     Most  of  loader.conf's  default  settings can be ignored.  The few of them
     which are important or useful are:

	   bitmap_load
		     ("NO") If set to "YES", a bitmap will be loaded to be  dis-
		     played on screen while booting.

	   bitmap_name
		     ("/boot/splash.bmp")  Name of the bitmap to be loaded.  Any
		     other name can be used.

	   comconsole_speed
		     ("9600" or the value of the BOOT_COMCONSOLE_SPEED	variable
		     when loader(8) was compiled).  Sets the speed of the serial
		     console.	If the previous boot loader stage specified that
		     a serial console is in use then the default speed is deter-
		     mined from the current serial port speed setting.

	   console   ("vidconsole")   "comconsole"   selects   serial	console,
		     "vidconsole"  selects  the video console, "nullconsole" se-
		     lects a mute console (useful for  systems	with  neither  a
		     video console nor a serial port), and "spinconsole" selects
		     the  video  console  which prevents any input and hides all
		     output replacing it with "spinning" character  (useful  for
		     embedded products and such).

	   screen.font
		     Set  font	size for framebuffer mode.  Default font size is
		     selected based on screen resolution,  to  achieve	terminal
		     dimensions 80x24.

	   screen.textmode
		     Value  "0"  will  trigger BIOS loader to switch to use VESA
		     BIOS Extension (VBE) frame buffer mode  for  console.   The
		     same effect can be achieved by setting vbe_max_resolution.

		     Value "1" will force BIOS loader to use VGA text mode.

		     If  vbe_max_resolution  is  not set, the loader will try to
		     set screen resolution based on EDID information.	If  EDID
		     is  not  available,  the  default resolution is 800x600 (if
		     available).

	   screen.height

	   screen.width

	   screen.depth
		     screen.height, screen.width, screen.depth are set by loader
		     when loader is using framebuffer mode to draw the screen.

	   efi_max_resolution

	   vbe_max_resolution
		     Specify the maximum desired resolution for the EFI  or  VBE
		     framebuffer console.  The following values are accepted:

		     Value	     Resolution
		     480p	     640x480
		     720p	     1280x720
		     1080p	     1920x1080
		     2160p	     3840x2160
		     4k 	     3840x2160
		     5k 	     5120x2880
		     WidthxHeight    WidthxHeight

	   kernel    ("kernel")

	   kernels   ("kernel kernel.old") Space or comma separated list of ker-
		     nels to present in the boot menu.

	   loader_conf_files
		     ("/boot/loader.conf /boot/loader.conf.local")

	   loader_conf_dirs
		     ("/boot/loader.conf.d")

	   splash_bmp_load
		     ("NO") If set to "YES", will load the splash screen module,
		     making  it  possible  to  display a bmp image on the screen
		     while booting.

	   splash_pcx_load
		     ("NO") If set to "YES", will load the splash screen module,
		     making it possible to display a pcx  image  on  the  screen
		     while booting.

	   vesa_load
		     ("NO") If set to "YES", the vesa module will be loaded, en-
		     abling bitmaps above VGA resolution to be displayed.

	   beastie_disable
		     If set to "YES", the beastie boot menu will be skipped.

	   loader_logo ("orbbw")
		     Selects  a desired logo in the beastie boot menu.	Possible
		     values  are:   "orbbw",   "orb",	"fbsdbw",   "beastiebw",
		     "beastie", and "none".

	   loader_color
		     If  set  to  "NO",  the beastie boot menu will be displayed
		     without ANSI coloring.

	   entropy_cache_load
		     ("YES") If set to "NO", the very  early  boot-time  entropy
		     file  will  not  be  loaded.   See  the  entropy entries in
		     rc.conf(5).

	   entropy_cache_name
		     ("/boot/entropy") The name of the very early boot-time  en-
		     tropy cache file.

	   cpu_microcode_load
		     ("NO") If set to "YES", the microcode update file specified
		     by cpu_microcode_name will be loaded and applied very early
		     during  boot.   This provides functionality similar to cpu-
		     control(8) but ensures that CPU features enabled by microc-
		     ode updates can be used by the kernel.  The update will  be
		     re-applied  automatically	when resuming from an ACPI sleep
		     state.  If the update file contains  updates  for	multiple
		     processor	models, the kernel will search for and extract a
		     matching update.  Currently this setting is supported  only
		     on  Intel	i386  and amd64 processors.  It has no effect on
		     other processor types.

	   cpu_microcode_name
		     A path to a microcode update file.

OTHER SETTINGS
     Other settings that may be used in loader.conf that have no default value:

	   fdt_overlays
		     Specifies a comma-delimited list of FDT overlays to  apply.
		     /boot/dtb/overlays is created by default for overlays to be
		     placed in.

	   kernels_autodetect
		     If  set  to "YES", attempt to auto-detect kernels installed
		     in /boot.	This is an  option  specific  to  the  Lua-based
		     loader.   It  is  not  available in the default Forth-based
		     loader.

FILES
     /boot/defaults/loader.conf  default settings -- do not change this file.
     /boot/loader.conf		 user defined settings.
     /boot/loader.conf.local	 machine-specific settings for sites with a com-
				 mon loader.conf.

SEE ALSO
     rc.conf(5), boot(8), cpucontrol(8), loader(8), loader.4th(8)

HISTORY
     The file loader.conf first appeared in FreeBSD 3.2.

AUTHORS
     This manual page was written by Daniel C. Sobral <dcs@FreeBSD.org>.

BUGS
     The loader(8) stops reading loader.conf when it encounters a syntax  error,
     so  any  options  which  are  vital  for booting a particular system (i.e.,
     "hw.ata.ata_dma=0")  should   precede   any   experimental   additions   to
     loader.conf.

FreeBSD 13.0			 January 6, 2021		  LOADER.CONF(5)
home | help