DragonFly On-Line Manual Pages
LOADER(8) DragonFly System Manager's Manual LOADER(8)
NAME
loader - kernel bootstrapping final stage
DESCRIPTION
The program called loader is the final stage of DragonFly's kernel
bootstrapping process. It is implemented as a BTX client and is linked
statically 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
possible 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 different 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
previous boot stage used that. Then, devices are probed, currdev and
loaddev are set, and LINES is set to 24. After that, dloader.rc is
processed 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. If the variable name contains a `.' it is considered a
kernel tunable. Local variables are unset if value is empty.
Kernel environment variable will have empty value.
In other words, the assignment above will set a local variable
and if applicable, also assign value to the kernel environment
variable, even if value is empty. See also KERNEL ENVIRONMENT
VARIABLES AND LOCAL VARIABLES.
Value can be a string or a string expression containing literal
text and kernel environment variables, like "$VAR" or "${VAR}".
Escape sequences like `\n' (newline), `\t' (TAB) and `\OOO'
(character with number given in octal) can also be used. This is
actually a general facility of loader which can be used for
arguments of all commands.
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
provided. 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. See description of assignment (variable=value)
value for use of kernel environment variables and escape
sequences in message.
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 path exists, i.e. file/dir present.
ifset kenv_variable
Conditional kernel environment variable kenv_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.
loadall
Load the kernel and all modules specified by MODULE_load
variables.
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 current
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
partition 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
variable.
lunsetif local_variable kenv_variable
Unset local variable local_variable if kernel environment
variable kenv_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
pressing key.
more file ...
Display the files specified, with a pause at each LINES
displayed.
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 [-p prompt] [-t seconds] [kenv_variable]
Reads a line of input from the terminal, storing it in kernel
environment variable kenv_variable if specified. A prompt may be
displayed through the -p flag. A timeout can be specified with
-t, though it will be canceled at the first key pressed.
reboot Immediately reboots the system.
set kenv_variable
set kenv_variable=value
Set kernel environment variable kenv_variable to the given value,
if no value is given, the empty string is the value.
show [kenv_variable]
Displays the specified kernel environment variable's value, or
all variables and their values if kenv_variable is not specified.
unload Removes all modules from memory.
unset kenv_variable
Removes kenv_variable from the kernel environment.
? Lists most available commands with a short help text for each.
KERNEL ENVIRONMENT VARIABLES AND LOCAL VARIABLES
The loader 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 loader, which
are not available to the kernel.
Both local variable and kernel environment variable of the same name are
changed by assignment (variable=value).
Kernel environment variables can be set and unset through the set and
unset builtins, and can have their values examined through the show and
ifset builtins. Variables in command arguments or value in assignments
("$VAR" and "${VAR}") refers to kernel environment variables.
Local variables can be unset with lunset and lunsetif builtin, and can
have their values examined through the local 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).
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.
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
Used for handling automatic loading of the acpi(4) module. To
disable automatic loading of the ACPI module use:
lunset acpi_load
set hint.acpi.0.disabled=1
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
processed 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_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. Defaults to
kernel.
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.
ehci_load
Used for handling automatic loading of the ehci(4) module. To
disable automatic loading of the EHCI module use:
lunset ehci_load
set hint.ehci.0.disabled=1
xhci_load
Used for handling automatic loading of the xhci(4) module. To
disable automatic loading of the XHCI module use:
lunset xhci_load
set hint.xhci.0.disabled=1
init_chroot
Directory init(8) will chroot() to on startup. By setting this
variable DragonFly can be run from a subdirectory of the root
file system.
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.
local_modules
Setting this variable to "YES" causes /boot/modules.local to be
included after modules_path directories list and passed to kernel
for kldload(8).
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". Kernel environment
variables can be used in prompt by including "${VAR}". E.g.
(note that `$' must be escaped with `\' to be included in
prompt):
set prompt="\${currdev} 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
number can be forced by setting this variable.
See also vfs.root.mountfrom variable.
rootdev
By default the value of currdev is used to set the root file
system when the kernel is booted. This can be overridden by
setting rootdev explicitly.
See also vfs.root.mountfrom variable.
Other variables are used to override kernel tunable parameters. The
following loader tunables are available:
hw.ioapic_enable
Control use of I/O APIC. Set to 1 to enable, 0 to disable.
Default is 1.
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
I/O APIC use is disabled.
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
suffixes 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
cannot be set below the default determined when the kernel was
compiled. Modifies NMBCLUSTERS.
kern.mmxopt
Toggles the mmx optimizations for the bcopy/copyin/copyout
routines
kern.user_scheduler
Default userland scheduler (usched). If set, values can be
"bsd4" or "dfly". Default is "dfly".
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
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 1/2 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 on 32-bit and
unspecified on 64-bit. This parameter 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.wakedelay
Specify an additional delay (default is 2 seconds if unspecified)
before trying to mount root.
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 /boot.
One file system example:
hammer:da8s1a
One file system HAMMER2 multi volume example:
hammer2:da8s1a:da9s1a
Several file systems, boot list, example:
ufs:da0s1a;hammer2: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
vfs.root.realroot
Root file system and extra options for initrd. See initrd(7).
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.
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.
FILES
/boot/boot.conf loader bootstrapping script. Deprecated
/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 loader itself
/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 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 ALSO
kenv(1), libstand(3), acpi(4), ehci(4), xhci(4), loader.conf(5),
tuning(7), boot(8), cryptsetup(8), lvm(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>.
BUGS
A variable can have two instances: local & kernel environment, this can
cause confusion.
DragonFly 6.1-DEVELOPMENT May 20, 2019 DragonFly 6.1-DEVELOPMENT