boot/common/loader.8

.\"
.\" Copyright (c) 1999 Daniel C. Sobral
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/sys/boot/common/loader.8,v 1.57 2003/06/29 20:57:55 brueffer Exp $
.\"
.Dd May 20, 2019
.Dt LOADER 8
.Os
.Sh NAME
.Nm loader
.Nd kernel bootstrapping final stage
.Sh DESCRIPTION
The program called
.Nm
is the final stage of
.Dx Ns 's
kernel bootstrapping process.
It is implemented as a
.Tn BTX
client and is linked statically to
.Xr libstand 3
and located in the
.Pa /boot
or
.Pa /
directory.
.Pp
If a
.Pa /boot
directory exist on the boot file system, then
.Dq /boot/
is prepended to all relative file names used by
.Nm .
This makes it possible to locate all files used by
.Nm
in either
.Pa /
or
.Pa /boot
directory on the boot file system.
If boot and root are the same file system, then files used by
.Nm
are located in
.Pa /boot .
If boot and root are different file systems, then files used by
.Nm
are located in
.Pa /
on the boot file system, which is mounted as
.Pa /boot
on the root file system when the kernel is running.
.Pp
During initialization,
.Nm
will probe for a console and set the
.Va console
variable, or set it to serial console
.Pq Dq comconsole
if the previous boot stage used that.
Then, devices are probed,
.Va currdev
and
.Va loaddev
are set, and
.Va LINES
is set to 24.
After that,
.Pa dloader.rc
is processed if available, and, failing that,
.Pa boot.conf
is read for historical reasons.
These files are processed through the
.Ic include
command, which reads all of them into memory before processing them,
making disk changes possible.
.Pp
At this point, if an
.Ic autoboot
has not been tried, and if
.Va autoboot_delay
is not set to
.Dq NO
(not case sensitive), then an
.Ic autoboot
will be tried.
If the system gets past this point,
.Va prompt
will be set and
.Nm
will engage interactive mode.
.Sh BUILTIN COMMANDS
In
.Nm ,
builtin commands take parameters from the command line.
.Pp
The builtin commands available are:
.Pp
.Bl -tag -width indent -compact
.It Ar variable Ns = Ns Ar value
Assign
.Ar value
to
.Ar variable .
The value is always assigned to a local variable
.Ar variable .
If
.Ar variable
is in the list of known kernel environment variables or is a kernel tunable,
the value is also assigned to the kernel environment variable of the
given name.
If the variable name contains a
.Ql .\&
it is considered a kernel tunable.
Local variables are unset if
.Ar value
is empty.
Kernel environment variable will have empty value.
.Pp
In other words, the assignment above will set a local variable and
if applicable, also assign
.Ar value
to the kernel environment variable, even if
.Ar value
is empty.
See also
.Sx KERNEL ENVIRONMENT VARIABLES AND LOCAL VARIABLES .
.Pp
.Ar Value
can be a string or a string expression containing literal text and
kernel environment variables, like
.Dq $VAR
or
.Dq ${VAR} .
Escape sequences like
.Ql \en
(newline),
.Ql \et
(TAB) and
.Ql \eOOO
(character with number given in octal)
can also be used.
This is actually a general facility of
.Nm
which can be used for arguments of all commands.
.Pp
.It Ic autoboot Op Ar delay Op Ar prompt
Proceeds to bootstrap the system after a number of seconds, if not
interrupted by the user.
Displays a countdown prompt
warning the user the system is about to be booted,
unless interrupted by a key press.
The kernel will be loaded first if necessary.
Defaults to 10 seconds.
.Pp
.It Ic bcachestat
Displays statistics about disk cache usage.
For depuration only.
.Pp
.It Ic boot Oo Fl Ns Ar flag ... Oc Op Ar kernelname
Immediately proceeds to bootstrap the system, loading the kernel
if necessary.
Any flags or arguments are passed to the kernel, but they
must precede the kernel name, if a kernel name is provided.
Flags are described in
.Xr boot 8 .
See also
.Va boot_*
and
.Va kernel_options
variables.
.Pp
.It Ic cd Op Ar directory
Change working directory to
.Ar directory .
Default is $base.
.Pp
.It Ic echo Oo Fl n Oc Op Ar message
Displays text on the screen.
A new line will be printed unless
.Fl n
is specified.
See description of assignment
.Pq Ar variable Ns = Ns Ar value
.Ar value
for use of kernel environment variables and escape sequences in
.Ar message .
.Pp
.It Ic else
Conditional if/else/endif.
.Pp
.It Ic elseifexists Ar path
Conditional
.Ar path
exists, i.e.\& file/dir present.
.Pp
.It Ic endif
Conditional if/else/endif.
.Pp
.It Ic heap
Displays memory usage statistics.
For debugging purposes only.
.Pp
.It Ic help Op Ar topic Op Ar subtopic
Shows help messages read from
.Pa loader.help .
The special
.Ar topic
.Cm index
will list all topics available.
.Pp
.It Ic ifexists Ar path
Conditional
.Ar path
exists, i.e.\& file/dir present.
.Pp
.It Ic ifset Ar kenv_variable
Conditional kernel environment variable
.Ar kenv_variable
exists.
.Pp
.It Ic include Ar
Process script files.
Each file, in turn, is completely read into memory,
and then each of its lines is passed to the command line interpreter.
If any error is returned by the interpreter, the include
command aborts immediately, without reading any other files, and
returns an error itself.
.Pp
.It Ic load Oo Fl t Ar type Oc Ar file Op Ar argument ...
Loads a kernel, kernel loadable module (kld), or file of opaque
contents tagged as being of the type
.Ar type .
Kernel and modules can be either in a.out or
.Tn ELF
format.
Any arguments passed after the name of the file to be loaded
will be passed as arguments to that file.
.Pp
.It Ic loadall
Load the kernel and all modules specified by MODULE_load variables.
.Pp
.It Ic local Op Ar local_variable ...
Displays the specified variable's value, or all local variables and their
values if
.Ar local_variable
is not specified.
.Pp
.It Ic ls Oo Fl l Oc Op Ar path
Displays a listing of files in the directory
.Ar path ,
or the current directory if
.Ar path
is not specified.
If
.Fl l
is specified, file sizes will be shown too.
.Pp
.It Ic lsdev Op Fl v
Lists all devices.
A
.Sq *
prefix indicates a disk slice or partition from which it may be
possible to load modules.
If
.Fl v
is specified, more details,
like disk slice or partition size and position, are printed.
.Pp
.It Ic lsmod Op Fl v
Displays loaded modules.
If
.Fl v
is specified, more details are shown.
.Pp
.It Ic lunset Ar local_variable
Unset a local variable.
Discards the value and removes the variable.
.Pp
.It Ic lunsetif Ar local_variable kenv_variable
Unset local variable
.Ar local_variable
if kernel environment variable
.Ar kenv_variable
is true, i.e.\& set to 1 or
.Ql YES .
.Pp
.It Ic menu
Run menu system.
.Pp
.It Ic menuadd Ar command_line
Add script line for the current menu item.
.Pp
.It Ic menuclear
Clear all menu items.
.Pp
.It Ic menuitem Ar key description
Start a new menu item.
When running the menu system, a line with
.Ar key
and
.Ar description
is displayed, and an item is chosen by pressing
.Ar key .
.Pp
.It Ic more Ar
Display the files specified, with a pause at each
.Va LINES
displayed.
.Pp
.It Ic optcd Op Ar directory
Change the working directory to
.Ar directory .
Default is $base.
Ignore errors.
This command is like
.Ic cd ,
but ignores errors when changing the directory.
.Pp
.It Ic optinclude Ar
Process script files.
Ignore errors.
This command is like
.Ic include ,
but ignores errors while executing commands in included files.
.Pp
.It Ic pnpscan Op Fl v
Scans for Plug-and-Play devices.
This is not functional at present.
.Pp
.It Ic pwd
Prints the working directory.
.Pp
.It Ic read Oo Fl p Ar prompt Oc Oo Fl t Ar seconds Oc Op Ar kenv_variable
Reads a line of input from the terminal,
storing it in kernel environment variable
.Ar kenv_variable
if specified.
A prompt may be displayed through the
.Fl p
flag.
A timeout can be specified with
.Fl t ,
though it will be canceled at the first key pressed.
.Pp
.It Ic reboot
Immediately reboots the system.
.Pp
.It Ic set Ar kenv_variable
.It Ic set Ar kenv_variable Ns = Ns Ar value
Set kernel environment variable
.Ar kenv_variable
to the given value,
if no
.Ar value
is given, the empty string is the value.
.Pp
.It Ic show Op Ar kenv_variable
Displays the specified kernel environment variable's value,
or all variables and their values if
.Ar kenv_variable
is not specified.
.Pp
.It Ic unload
Removes all modules from memory.
.Pp
.It Ic unset Ar kenv_variable
Removes
.Ar kenv_variable
from the kernel environment.
.Pp
.It Ic \&?
Lists most available commands with a short help text for each.
.El
.Ss KERNEL ENVIRONMENT VARIABLES AND LOCAL VARIABLES
The
.Nm
actually has two different kinds of variables.
These are
kernel environment variables,
which are visible to the kernel when it is started,
and a separate space of local variables used by
.Nm ,
which are not available to the kernel.
.Pp
Both local variable and kernel environment variable
of the same name are changed by assignment
.Pq Ar variable Ns = Ns Ar value .
.Pp
Kernel environment variables can be set and unset through the
.Ic set
and
.Ic unset
builtins, and can have their values examined through the
.Ic show
and
.Ic ifset
builtins.
Variables in command arguments or
.Ar value
in assignments
.Dq ( $VAR
and
.Dq ${VAR} )
refers to kernel environment variables.
.Pp
Local variables can be unset with
.Ic lunset
and
.Ic lunsetif
builtin, and can have their values examined through the
.Ic local
builtin.
.Pp
Notice that these environment variables are not inherited by any shell
after the system has been booted, but can be examined by
.Xr kenv 1 .
.Pp
Note that a variable can have two instances with differnet values:
both a local variable instance and a kernel environment variable instance
can exist for the same name and with different values.
This can cause confusion and is seldom done on purpose.
.Pp
A few variables are set automatically by
.Nm .
Others can affect the behavior of either
.Nm
or the kernel at boot.
Some options may require a value,
while others define behavior just by being set.
Both types of variables are described below.
.Bl -tag -width indent
.It Va acpi_load
Used for handling automatic loading of the
.Xr acpi 4
module.
To disable automatic loading of the ACPI module use:
.Pp
.Dl lunset acpi_load
.Dl set hint.acpi.0.disabled=1
.It Va autoboot_delay
Number of seconds
.Ic autoboot
and
.Ic menu
will wait before booting.
Default value is 10 seconds.
.Pp
If set to
.Dq NO ,
no
.Ic autoboot
will be automatically attempted after processing
.Pa dloader.rc ,
though explicit
.Ic autoboot Ns 's
will be processed normally, defaulting to 10 seconds delay.
.It Va boot_askname
Instructs the kernel to prompt the user for the name of the root device
when the kernel is booted.
.It Va boot_ddb
Instructs the kernel to start in the DDB debugger, rather than
proceeding to initialize when booted.
.It Va boot_gdb
Selects gdb-remote mode for the kernel debugger by default.
.It Va boot_single
Prevents the kernel from initiating a multi-user startup; instead single-user
mode will be entered when the kernel has finished device probing.
.It Va boot_verbose
Setting this variable causes extra debugging information to be printed
by the kernel during and after the boot phase.
.It Va bootfile
List of semicolon-separated search path for bootable kernels.
The default is
.Dq Li kernel .
.It Va console
Defines the current console.
.It Va currdev
Selects the default device.
Syntax for devices is odd.
.It Va default_kernel
Selects default kernel loaded by
.Ic menu
command.
Defaults to
.Pa kernel .
.It Va dumpdev
The name of a device where the kernel can save a crash dump in case
of a panic.
This automatically sets the
.Va kern.dumpdev
.Xr sysctl 3
.Tn MIB
variable.
.It Va ehci_load
Used for handling automatic loading of the
.Xr ehci 4
module.
To disable automatic loading of the EHCI module use:
.Pp
.Dl lunset ehci_load
.Dl set hint.ehci.0.disabled=1
.It Va xhci_load
Used for handling automatic loading of the
.Xr xhci 4
module.
To disable automatic loading of the XHCI module use:
.Pp
.Dl lunset xhci_load
.Dl set hint.xhci.0.disabled=1
.It Va init_chroot
Directory
.Xr init 8
will
.Fn chroot
to on startup.
By setting this variable
.Dx
can be run from a subdirectory of the root file system.
.It Va init_path
Sets the list of binaries which the kernel will try to run as the initial
process.
The first matching binary is used.
The default list is
.Dq Li /sbin/init:/sbin/oinit:/sbin/init.bak .
.It Va kernel_options
Set kernel boot flags.
See also
.Ic boot
command.
.It Va LINES
Define the number of lines on the screen, to be used by the pager.
.It Va local_modules
Setting this variable to
.Dq Li YES
causes
.Pa /boot/modules.local
to be included after
.Va modules_path
directories list and passed to kernel for
.Xr kldload 8 .
.It Va module_path
Sets the list of directories which will be searched for modules named in a
.Nm load
command or implicitly required by a dependency.
The default value for this variable is
.Dq Li ;modules ,
which first searches the current working directory and then
.Pa modules .
.It Va num_ide_disks
Sets the number of IDE disks as a workaround for some problems in
finding the root disk at boot.
This has been deprecated in favor of
.Va root_disk_unit .
.It Va prompt
Value of
.Nm Ns 's
prompt.
Defaults to
.Dq Li OK .
Kernel environment variables can be used in
.Va prompt
by including
.Dq Li ${VAR} .
E.g. (note that
.Ql $
must be escaped with
.Ql \e
to be included in
.Va prompt ) :
.Pp
.Dl "set prompt=\*q\e${currdev} OK\*q"
.It Va root_disk_unit
If the code which detects the disk unit number for the root disk is
confused, e.g.\& by a mix of
.Tn SCSI
and
.Tn IDE
disks, or
.Tn IDE
disks with
gaps in the sequence (e.g.\& no primary slave), the unit number can
be forced by setting this variable.
.Pp
See also
.Va vfs.root.mountfrom
variable.
.It Va rootdev
By default the value of
.Va currdev
is used to set the root file system
when the kernel is booted.
This can be overridden by setting
.Va rootdev
explicitly.
.Pp
See also
.Va vfs.root.mountfrom
variable.
.El
.Pp
Other variables are used to override kernel tunable parameters.
The following
.Nm
tunables are available:
.Bl -tag -width indent
.It Va hw.ioapic_enable
Control use of
.Tn I/O APIC .
Set to 1 to enable, 0 to disable.
Default is 1.
.It Va hw.irq.X.dest
Set irqX's destination to the given
.Tn CPUID ,
which starts from 0.
If the specified value is larger than the last
.Tn CPUID ,
then the first
.Tn CPUID
will be used.
This variable should not be used if
.Tn I/O APIC
use is disabled.
.It Va hw.physmem
Limit the amount of physical memory the system will use.
By default the size is in bytes, but the
.Cm k , K , m , M , g
and
.Cm G
suffixes
are also accepted and indicate kilobytes, megabytes and gigabytes
respectively.
An invalid suffix will result in the variable being ignored by the
kernel.
.It Va hw.usb.hack_defer_exploration
The USB keyboard will sometimes not attach properly unless you set this
variable to 0.
.It Va kern.emergency_intr_enable
Setting this to 1 enables emergency interrupt polling.
All interrupt handlers are executed periodically.
This mode is very expensive and should
only be used to get a system accessible when interrupt routing is
otherwise broken.
It is primarily used by kernel developers to debug new systems.
.It Va kern.emergency_intr_freq
Set the polling rate for the emergency interrupt polling code.
The default is 10 (hz) to dissuade casual use.
If you are doing real work
with emergency interrupt polling mode enabled, it is recommended
that you use a frequency between 100hz and 300hz.
.It Va kern.maxusers
Set the size of a number of statically allocated system tables; see
.Xr tuning 7
for a description of how to select an appropriate value for this tunable.
When set, this tunable replaces the value declared in the kernel
compile-time configuration file.
.It Va kern.ipc.nmbclusters
Set the number of mbuf clusters to be allocated.
The value cannot be set below the default
determined when the kernel was compiled.
Modifies
.Va NMBCLUSTERS .
.It Va kern.mmxopt
Toggles the mmx optimizations for the bcopy/copyin/copyout routines
.It Va kern.user_scheduler
Default userland scheduler (usched).
If set, values can be
.Dq bsd4
or
.Dq dfly .
Default is
.Dq dfly .
.It Va kern.vm.kmem.size
Sets the size of kernel memory (bytes).
This overrides the value determined when the kernel was compiled.
.It Va kern.maxswzone
Limits the amount of
.Tn KVM
to be used to hold swap
meta information, which directly governs the
maximum amount of swap the system can support.
This value is specified in bytes of KVA space
and defaults to around 70MBytes.
Care should be taken
to not reduce this value such that the actual
amount of configured swap exceeds \(12 the
kernel-supported swap.
The default 70MB allows
the kernel to support a maximum of (approximately)
14GB of configured swap.
Only mess around with
this parameter if you need to greatly extend the
.Tn KVM
reservation for other resources such as the
buffer cache or
.Va NMBCLUSTERS .
Modifies
.Va VM_SWZONE_SIZE_MAX .
.It Va kern.maxbcache
Limits the amount of KVM reserved for use by the
buffer cache, specified in bytes.
The default maximum is 200MB on 32-bit and
unspecified on 64-bit.
This parameter is used to
prevent the buffer cache from eating too much
.Tn KVM
in large-memory machine configurations.
Only mess around with this parameter if you need to
greatly extend the
.Tn KVM
reservation for other resources
such as the swap zone or
.Va NMBCLUSTERS .
Note that
the NBUF parameter will override this limit.
Modifies
.Va VM_BCACHE_SIZE_MAX .
.It Va machdep.disable_mtrrs
Disable the use of
.Sy i686
.Tn MTRRs
(x86 only).
.It Va net.inet.tcp.tcbhashsize
Overrides the compile-time set value of
.Va TCBHASHSIZE
or the preset default of 512.
Must be a power of 2.
.It Va vfs.root.wakedelay
Specify an additional delay (default is 2 seconds if unspecified)
before trying to mount root.
.It Va vfs.root.mountfrom
Specify root file system.
A semicolon separated list of file systems to try
as the kernel root file system.
File system format is file system type and disk store,
separated by colon.
This variable needs to be set when using a boot-only partition, which is
typically mounted on root file system as
.Pa /boot .
.Pp
One file system example:
.Dl hammer:da8s1a
.Pp
One file system
.Nm HAMMER2
multi volume example:
.Dl hammer2:da8s1a:da9s1a
.Pp
Several file systems, boot list, example:
.Dl ufs:da0s1a;hammer2:ad1s1d
.Pp
Each file system in the list will be tried in the order specified
until the mount succeeds.
If all fail, the
.Ql mountroot>
prompt is displayed for manual entry.
.Pp
You may not specify devtab labels here but you can specify paths available to
.Xr devfs 5
such as:
.Dl hammer:serno/L41JYE0G.s1d
.It Va vfs.root.realroot
Root file system and extra options for
.Nm initrd .
See
.Xr initrd 7 .
.It Va nfsroot.iosize
Override the default NFS netbooted root mount io block size.
The default is 8192 which works with most servers.
suggested values are 8192, 16384, or 32768.
.It Va nfsroot.rahead
Override the default read-ahead used by netbooted root mounts.
The default is 4 which is reasonable.  Suggested values are 1 through 8.
.El
.Sh FILES
.Bl -tag -width /boot/defaults/dloader.menu -compact
.It Pa /boot/boot.conf
.Nm
bootstrapping script.
Deprecated
.It Pa /boot/defaults/dloader.menu
.Nm
menu setup commands -- do not change this file
.It Pa /boot/defaults/loader.conf
.Nm
configuration file, see
.Xr loader.conf 5
-- do not change this file
.It Pa /boot/dloader.menu
.Nm
menu setup commands
.It Pa /boot/dloader.rc
.Nm
bootstrapping script
.It Pa /boot/loader
.Nm
itself
.It Pa /boot/loader.conf
.It Pa /boot/loader.conf.local
.Nm
configuration files, see
.Xr loader.conf 5
.It Pa /boot/loader.help
help messages, used by the
.Ic help
command
.El
.Sh EXAMPLES
Boot in single user mode:
.Pp
.Dl loadall
.Dl boot -s
.Pp
Load the kernel, a splash screen, and then autoboot in five seconds.
.Bd -literal -offset indent
load kernel
load splash_bmp
load -t splash_image_data chuckrulez.bmp
autoboot 5
.Ed
.Pp
Set the disk unit of the root device to 2, and then boot.
This would be needed in a system with two IDE disks,
with the second IDE disk hardwired to
.Pa ad2
instead of
.Pa ad1 .
.Bd -literal -offset indent
set root_disk_unit=2
boot kernel
.Ed
.Sh SEE ALSO
.Xr kenv 1 ,
.Xr libstand 3 ,
.Xr acpi 4 ,
.Xr ehci 4 ,
.Xr xhci 4 ,
.Xr loader.conf 5 ,
.Xr tuning 7 ,
.Xr boot 8 ,
.Xr cryptsetup 8 ,
.Xr lvm 8 ,
.Xr pxeboot 8 ,
.Xr pxeboot_tftp 8 ,
.Xr sysctl 8
.Sh HISTORY
The
.Nm
first appeared in
.Fx 3.1 .
.Nm dloader
was introduced and
.Tn FORTH
removed in
.Dx 2.7 .
.Sh AUTHORS
.An -nosplit
The
.Nm
was written by
.An Michael Smith Aq Mt msmith@FreeBSD.org .
.Pp
.Nm dloader
was written by
.An Matthew Dillon Aq Mt dillon@backplane.com .
.Sh BUGS
A variable can have two instances: local & kernel environment,
this can cause confusion.