LOADER(8) BSD System Manager's Manual LOADER(8)NAMEloader — kernel bootstrapping final stage
DESCRIPTION
The program called loader is the final stage of DragonFly's kernel boot‐
strapping process. It is implemented as a BTX client and is linked stat‐
ically to libstand(3) and located in the /boot or / directory.
If a /boot directory exist on the boot file system, then “/boot/” is
prepended to all relative file names used by loader. This makes it pos‐
sible to locate all files used by loader in either / or /boot directory
on the boot file system. If boot and root are the same file system, then
files used by loader are located in /boot. If boot and root are differ‐
ent file systems, then files used by loader are located in / on the boot
file system, which is mounted as /boot on the root file system when the
kernel is running.
During initialization, loader will probe for a console and set the
console variable, or set it to serial console (“comconsole”) if the pre‐
vious boot stage used that. Then, devices are probed, currdev and
loaddev are set, and LINES is set to 24. After that, dloader.rc is pro‐
cessed if available, and, failing that, boot.conf is read for historical
reasons. These files are processed through the include command, which
reads all of them into memory before processing them, making disk changes
possible.
At this point, if an autoboot has not been tried, and if autoboot_delay
is not set to “NO” (not case sensitive), then an autoboot will be tried.
If the system gets past this point, prompt will be set and loader will
engage interactive mode.
BUILTIN COMMANDS
In loader, builtin commands take parameters from the command line.
The builtin commands available are:
variable=value
Assign value to variable. The value is always assigned to a
local variable variable. If 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 value is empty. Kernel envi‐
ronment variables may have empty values.
In other words, the assignment above will set a local variable
and if it is applicable, also assign value to the kernel environ‐
ment variable, even if value is empty. See also ENVIRONMENT
VARIABLES AND LOCAL VARIABLES.
autoboot [delay [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.
bcachestat
Displays statistics about disk cache usage. For depuration only.
boot [-flag ...] [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 pro‐
vided. Flags are described in boot(8). See also boot_* and
kernel_options variables.
cd [directory]
Change working directory to directory. Default is $base.
echo [-n] [message]
Displays text on the screen. A new line will be printed unless
-n is specified.
else Conditional if/else/endif.
elseifexists path
Conditional path exists, i.e. file/dir present.
endif Conditional if/else/endif.
heap Displays memory usage statistics. For debugging purposes only.
help [topic [subtopic]]
Shows help messages read from loader.help. The special topic
index will list all topics available.
ifexists path
Conditional Ar path exists, i.e. file/dir present.
ifset env_variable
Conditional env_variable exists.
include file ...
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.
load [-t type] file [argument ...]
Loads a kernel, kernel loadable module (kld), or file of opaque
contents tagged as being of the type type. Kernel and modules
can be either in a.out or 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.
loadall
Load the kernel and all modules specified by MODULE_load vari‐
ables.
local [local_variable ...]
Displays the specified variable's value, or all local variables
and their values if local_variable is not specified.
ls [-l] [path]
Displays a listing of files in the directory path, or the root
directory if path is not specified. If -l is specified, file
sizes will be shown too.
lsdev [-v]
Lists all devices. A ‘*’ prefix indicates a disk slice or parti‐
tion from which it may be possible to load modules. If -v is
specified, more details, like disk slice or partition size and
position, are printed.
lsmod [-v]
Displays loaded modules. If -v is specified, more details are
shown.
lunset local_variable
Unset a local variable. Discards the value and removes the vari‐
able.
lunsetif local_variable env_variable
Unset local_variable if env_variable is true, i.e. set to 1 or
‘YES’.
menu Run menu system.
menuadd command_line
Add script line for the current menu item.
menuclear
Clear all menu items.
menuitem key description
Start a new menu item. When running the menu system, a line with
key and description is displayed, and an item is chosen by press‐
ing key.
more file ...
Display the files specified, with a pause at each LINES dis‐
played.
optcd [directory]
Change the working directory to directory. Default is $base.
Ignore errors. This command is like cd, but ignores errors when
changing the directory.
optinclude file ...
Process script files. Ignore errors. This command is like
include, but ignores errors while executing commands in included
files.
pnpscan [-v]
Scans for Plug-and-Play devices. This is not functional at
present.
pwd Prints the working directory.
read [-t seconds] [-p prompt] [env_variable]
Reads a line of input from the terminal, storing it in
env_variable if specified. A timeout can be specified with -t,
though it will be canceled at the first key pressed. A prompt
may also be displayed through the -p flag.
reboot Immediately reboots the system.
set env_variable
set env_variable=value
Set loader's environment variables.
show [env_variable]
Displays the specified kernel environment variable's value, or
all variables and their values if env_variable is not specified.
unload Removes all modules from memory.
unset env_variable
Removes env_variable from the environment.
? Lists most available commands with a short help text for each.
ENVIRONMENT VARIABLES AND LOCAL VARIABLES
The loader has actually two different kinds of variables. There are ker‐
nel environment variables, which are visible to the kernel when it is
run, and a separate space of local variables used by loader, which are
not available to the kernel.
Environment variables can be set and unset through the set and unset
builtins, and can have their values interactively examined through the
use of the show builtin.
Notice that these environment variables are not inherited by any shell
after the system has been booted, but can be examined by kenv(1).
A few variables are set automatically by loader. Others can affect the
behavior of either loader 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.
acpi_load
Unset this to disable automatic loading of the ACPI module.
autoboot_delay
Number of seconds autoboot and menu will wait before booting.
Default value is 10 seconds.
If set to “NO”, no autoboot will be automatically attempted after
processing dloader.rc, though explicit autoboot's will be pro‐
cessed normally, defaulting to 10 seconds delay.
boot_askname
Instructs the kernel to prompt the user for the name of the root
device when the kernel is booted.
boot_ddb
Instructs the kernel to start in the DDB debugger, rather than
proceeding to initialize when booted.
boot_gdb
Selects gdb-remote mode for the kernel debugger by default.
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.
boot_userconfig
Requests that the kernel's interactive device configuration pro‐
gram be run when the kernel is booted.
boot_verbose
Setting this variable causes extra debugging information to be
printed by the kernel during and after the boot phase.
bootfile
List of semicolon-separated search path for bootable kernels.
The default is “kernel”.
console
Defines the current console.
currdev
Selects the default device. Syntax for devices is odd.
default_kernel
Selects default kernel loaded by menu command.
ehci_load
Unset this to disable automatic loading of the EHCI module.
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 “/sbin/init:/sbin/oinit:/sbin/init.bak”.
kernel_options
Set kernel boot flags. See also boot command.
LINES Define the number of lines on the screen, to be used by the
pager.
module_path
Sets the list of directories which will be searched for modules
named in a load command or implicitly required by a dependency.
The default value for this variable is “;modules”, which first
searches the current working directory and then modules.
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 root_disk_unit.
prompt Value of loader's prompt. Defaults to “OK”.
root_disk_unit
If the code which detects the disk unit number for the root disk
is confused, e.g. by a mix of SCSI and IDE disks, or IDE disks
with gaps in the sequence (e.g. no primary slave), the unit num‐
ber can be forced by setting this variable.
rootdev
By default the value of currdev is used to set the root file sys‐
tem when the kernel is booted. This can be overridden by setting
rootdev explicitly.
dumpdev
The name of a device where the kernel can save a crash dump in
case of a panic. This automatically sets the kern.dumpdev
sysctl(3) MIB variable.
Other variables are used to override kernel tunable parameters. The fol‐
lowing loader tunables are available:
hw.irq.X.dest
Set irqX's destination to the given CPUID, which starts from 0.
If the specified value is larger than the last CPUID, then the
first CPUID will be used. This variable should not be used if
IO/APIC support is not compiled into kernel.
hw.physmem
Limit the amount of physical memory the system will use. By
default the size is in bytes, but the k, K, m, M, g and G suf‐
fixes are also accepted and indicate kilobytes, megabytes and
gigabytes respectively. An invalid suffix will result in the
variable being ignored by the kernel.
hw.usb.hack_defer_exploration
The USB keyboard will sometimes not attach properly unless you
set this variable to 0.
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.
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.
kern.maxusers
Set the size of a number of statically allocated system tables;
see 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.
kern.ipc.nmbclusters
Set the number of mbuf clusters to be allocated. The value can‐
not be set below the default determined when the kernel was com‐
piled. Modifies NMBCLUSTERS.
kern.mmxopt
Toggles the mmx optimizations for the bcopy/copyin/copyout rou‐
tines
kern.vm.kmem.size
Sets the size of kernel memory (bytes). This overrides the value
determined when the kernel was compiled.
kern.maxswzone
Limits the amount of KVM to be used to hold swap meta informa‐
tion, which directly governs the maximum amount of swap the sys‐
tem 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 ½ 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 KVM reservation for other resources such as
the buffer cache or NMBCLUSTERS. Modifies VM_SWZONE_SIZE_MAX.
kern.maxbcache
Limits the amount of KVM reserved for use by the buffer cache,
specified in bytes. The default maximum is 200MB. This parame‐
ter is used to prevent the buffer cache from eating too much KVM
in large-memory machine configurations. Only mess around with
this parameter if you need to greatly extend the KVM reservation
for other resources such as the swap zone or NMBCLUSTERS. Note
that the NBUF parameter will override this limit. Modifies
VM_BCACHE_SIZE_MAX.
machdep.disable_mtrrs
Disable the use of i686 MTRRs (x86 only).
net.inet.tcp.tcbhashsize
Overrides the compile-time set value of TCBHASHSIZE or the preset
default of 512. Must be a power of 2.
vfs.root.mountfrom
Specify root file system. A semicolon separated list of file
systems to try as the kernel root file system. File system for‐
mat 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 /boot.
One file system example:
hammer:da8s1a
One file system HAMMER multi volume example:
hammer:da8s1a:da9s1a
Several file systems, boot list, example:
ufs:da0s1a;hammer:ad1s1d
Each file system in the list will be tried in the order specified
until the mount succeeds. If all fail, the ‘mountroot>’ prompt
is displayed for manual entry.
You may not specify devtab labels here but you can specify paths
available to devfs(5) such as:
hammer:serno/L41JYE0G.s1d
FILES
/boot/boot.conf loader bootstrapping script. Deprecated.
/boot/loader loader itself.
/boot/defaults/dloader.menu loader menu setup commands -- do not change
this file.
/boot/defaults/loader.conf loader configuration file, see
loader.conf(5)-- do not change this file.
/boot/dloader.menu loader menu setup commands.
/boot/dloader.rc loader bootstrapping script.
/boot/loader.conf
/boot/loader.conf.local loader configuration files, see
loader.conf(5).
/boot/loader.help help messages, used by the help command.
EXAMPLES
Boot in single user mode:
loadall
boot -s
Load kernel's user configuration file. Notice that a kernel must be
loaded before any other load command is attempted.
load kernel
load -t userconfig_script kernel.conf
Load the kernel, a splash screen, and then autoboot in five seconds.
load kernel
load splash_bmp
load -t splash_image_data chuckrulez.bmp
autoboot 5
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 ad2 instead of ad1.
set root_disk_unit=2
boot kernel
SEE ALSOlibstand(3), loader.conf(5), tuning(7), boot(8), btxld(8), pxeboot(8),
pxeboot_tftp(8), sysctl(8)HISTORY
The loader first appeared in FreeBSD 3.1. dloader was introduced and
FORTH removed in DragonFly 2.7.
AUTHORS
The loader was written by Michael Smith ⟨msmith@FreeBSD.org⟩.
dloader was written by Matthew Dillon ⟨dillon@backplane.com⟩.
BSD October 6, 2010 BSD
