[dragonfly.git] / sys / 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 October 6, 2010
.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.
Local variables are unset if
.Ar value
is empty.
Kernel environment variables may have empty values.
.Pp
In other words, the assignment above will set a local variable and
if it is applicable, also assign
.Ar value
to the kernel environment variable, even if
.Ar value
is empty.
See also
.Sx ENVIRONMENT VARIABLES AND LOCAL VARIABLES .
.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 .
.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.
.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 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.
Currently, argument passing does not work for the kernel.
.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 root 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 env_variable
Unset
.Ar local_variable
if
.Ar env_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 t Ar seconds Oc Oo Fl p Ar prompt Oc Op Ar env_variable
Reads a line of input from the terminal, storing it in
.Ar env_variable
if specified.
A timeout can be specified with
.Fl t ,
though it will be canceled at the first key pressed.
A prompt may also be displayed through the
.Fl p
flag.
.Pp
.It Ic reboot
Immediately reboots the system.
.Pp
.It Ic set Ar env_variable
.It Ic set Ar env_variable Ns = Ns Ar value
Set
.Nm Ns 's
environment variables.
.Pp
.It Ic show Op Ar env_variable
Displays the specified kernel environment variable's value,
or all variables and their values if
.Ar env_variable
is not specified.
.Pp
.It Ic unload
Removes all modules from memory.
.Pp
.It Ic unset Ar env_variable
Removes
.Ar env_variable
from the environment.
.Pp
.It Ic \&?
Lists most available commands with a short help text for each.
.El
.Ss ENVIRONMENT VARIABLES AND LOCAL VARIABLES
The
.Nm
has actually two different kinds of variables.
There are
kernel environment variables, which are visible to the kernel when it is run,
and a separate space of local variables used by
.Nm ,
which are not available to the kernel.
.Pp
Environment variables can be set and unset through the
.Ic set
and
.Ic unset
builtins, and can have their values interactively examined through the
use of the
.Ic show
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
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
Unset this to disable automatic loading of the ACPI module.
.It Va autoboot_delay
Number of seconds
.Ic autoboot
will wait before booting.
If this variable is not defined,
.Ic autoboot
will default to 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_userconfig
Requests that the kernel's interactive device configuration program
be run when the kernel is booted.
.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;kernel.old .
.It Va console
Defines the current console.
.It Va currdev
Selects the default device.
Syntax for devices is odd.
.It Va ehci_load
Unset this to disable automatic loading of the EHCI module.
.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 LINES
Define the number of lines on the screen, to be used by the pager.
.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 .
.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.
.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.
.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.
.El
.Pp
Other variables are used to override kernel tunable parameters.
The following
.Nm
tunables are available:
.Bl -tag -width indent
.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 IO/APIC
support is not compiled into kernel.
.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.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.
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.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 HAMMER
multi volume example:
.Dl hammer:da8s1a:da9s1a
.Pp
Several file systems, boot list, example:
.Dl ufs:da0s1a;hammer: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
.El
.Sh FILES
.Bl -tag -width /boot/defaults/dloader.menu -compact
.It Pa /boot/boot.conf
.Nm
bootstrapping script.
Deprecated.
.It Pa /boot/loader
.Nm
itself.
.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.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 kernel's user configuration file.
Notice that a kernel must be loaded before any other
.Ic load
command is attempted.
.Bd -literal -offset indent
load kernel
load -t userconfig_script kernel.conf
.Ed
.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 libstand 3 ,
.Xr loader.conf 5 ,
.Xr tuning 7 ,
.Xr boot 8 ,
.Xr btxld 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 msmith@FreeBSD.org .
.Pp
.Nm dloader
was written by
.An Matthew Dillon Aq dillon@backplane.com .