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.isa.pnp_disabled
    If set to 1, skip the ISA PnP isolation scan. The scan takes several seconds on systems with no ISA PnP hardware, such as virtual machines. Default is 0.

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.tsc_cputimer_force
    If set to 1 and a TSC is present, the system will force invariant and MP synchronization operation for the TSC and always use the TSC as the CPU timer. This is primarily useful for running as a guest in QEMU.

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.intr_config_hook_delay_ms
    Specify how long to linger, in milliseconds, after the interrupt-driven device configuration hooks have finished but before mounting the root file system (default is 5000 if unspecified). It may be set to 0 to skip the delay entirely.

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 ½ 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_ms
    Specify an additional delay in milliseconds (default is 2000 if unspecified) before trying to mount root. This supersedes the seconds-based vfs.root.wakedelay tunable, which it replaces.

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.

vm.dma_reserved
    Override the amount of low-address memory reserved for potential 32-bit DMA space allocations and drm(4) buffer allocations. The value accepts the k, K, m, M, g and G suffixes to indicate kilobytes, megabytes and gigabytes, respectively.

FILES
/boot/boot.conf
    loader bootstrapping script. Deprecated
/boot/defaults/dloader.menu
    loader menu setup commands. Note: do not change this file.
/boot/defaults/loader.conf
    loader configuration file, see loader.conf(5). Note: 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
-nosplit 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.