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 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 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 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. 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 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. 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 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 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 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 kenv_variable Unset local variable local_variable if kernel environment vari- able 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 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 [-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 ker- nel 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 confu- sion 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_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. 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 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. 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 environ- ment 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 num- ber 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 sys- tem 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 fol- lowing 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 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.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 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 1/2 the kernel-supported swap. The default 70MB allows the kernel to support a maximum of (approximately) 14GB of con- figured 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 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 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 mkinitrd(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 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 ALSO

kenv(1), libstand(3), acpi(4), ehci(4), loader.conf(5), tuning(7), boot(8), btxld(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 3.7 October 21, 2012 DragonFly 3.7