NAME
boot.cfg —
configuration file for
/boot
DESCRIPTION
The file
/boot.cfg is used to alter the behaviour of the
standard boot loader described in
boot(8). Configuration changes
include setting the timeout, choosing a console device, altering the banner
text and displaying a menu allowing boot commands to be easily chosen. If a
boot.cfg file is not present, the system will boot as
normal.
The format of the file is a series of lines containing keyword/value pairs
separated by an equals sign (‘=’). There should be no whitespace
surrounding the equals sign. Lines beginning with a hash (‘#’) are
comments and will be ignored.
Some keywords can be present multiple times in the file to define additional
items. Such keywords are noted below.
-
-
- banner
- (may be present multiple times) The text from banner lines
is displayed instead of the standard welcome text by the boot loader. Up
to 10 lines can be defined. No special character sequences are recognised,
so to specify a blank line, a banner line with no value should be
given.
-
-
- clear
- If nonzero, clear the screen before printing the banner. If
zero, do not clear the screen (the default).
-
-
- consdev
- Changes the console device to that specified in the value.
Valid values are any of those that could be specified at the normal boot
prompt with the consdev command.
-
-
- default
- Used to specify the default menu item which will be chosen
in the case of Return being pressed or the timeout timer reaching zero.
The value is the number of the menu item as displayed. As described above,
the menu items are counted from 1 in the order listed in
boot.cfg. If not specified, the default value will be
option 1, i.e. the first item.
-
-
- format
- Changes how the menu options are displayed. Should be set
to one of ‘a’ for automatic, ‘l’ for letters and
‘n’ for numbers. If set to automatic (the default), menu
options will be displayed numerically unless there are more than 9 options
and the timeout is greater than zero. If there are more than 9 options
with a timeout greater than zero and the format is set to number, only the
first 9 options will be available.
-
-
- load
- Used to load kernel modules, which will be passed on to the
kernel for initialization during early boot. The argument is either the
complete path and file name of the module to be loaded, or a symbolic
module name. When the argument is not an absolute path, the boot loader
will first attempt to load
/stand/<machine>/<kernel_version>/modules/<name>/<name>.kmod.
If that file does not exist, it will then attempt to load
/<name>. May be used as many times as needed.
-
-
- menu
- (may be present multiple times) Used to define a menu item
to be displayed to the end-user at boot time which allows a series of boot
commands to be run without further typing. The value consists of the
required menu text, followed by a colon (‘:’) and then the
desired command(s). Multiple commands can be specified separated by a
semi-colon. If the specified menu text is empty (the colon appears
immediately after the equals sign), then the displayed menu text is the
same as the command. For example:
menu=Boot normally:boot
menu=Boot single-user:boot -s
menu=Boot with module foo:load /foo.kmod;boot
menu=Boot with serial console:consdev com0;boot
menu=:boot hd1a:netbsd -as
Each menu item will be prefixed by an ascending number when displayed, i.e.
the order in the boot.cfg file is important.
Each command is executed just as though the user had typed it in and so can
be any valid command that would be accepted at the normal boot prompt. In
addition, “prompt” can be used to drop to
the normal boot prompt.
-
-
- rndseed
- Takes the path to a random-seed file as written by the
-S flag to
rndctl(8) as an argument.
This file is used to seed the kernel entropy pool
rnd(9) very early in kernel
startup, so that high quality randomness is available to all kernel
modules. This argument should be supplied before any
“load” commands that may load executable
modules.
-
-
- timeout
- If the value is greater than zero, this specifies the time
in seconds that the boot loader will wait for the end-user to choose a
menu item. During the countdown period, they may press Return to choose
the default option or press a number key corresponding to a menu option.
If any other key is pressed, the countdown will stop and the user will be
prompted to choose a menu option with no further time limit. If the
timeout value is set to zero, the default option will be booted
immediately. If the timeout value is negative or is not a number, there
will be no time limit for the user to choose an option.
-
-
- userconf
- Passes a
userconf(4) command to the
kernel at boot time.
EXAMPLES
Here is an example
boot.cfg file:
banner=Welcome to NetBSD
banner==================
banner=
banner=Please choose an option from the following menu:
menu=Boot normally:boot
menu=Boot single-user:boot -s
menu=Boot from second disk:boot hd1a:
menu=Boot with module foo:load /foo.kmod;boot
menu=Boot with modules foo and bar:load /foo.kmod;load /bar.kmod;boot
menu=Boot Xen with 256MB for dom0:load /netbsd-XEN3_DOM0 console=pc;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M
menu=Boot Xen with 256MB for dom0 (serial):load /netbsd-XEN3_DOM0 console=com0;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M console=com1 com1=115200,8n1
menu=Boot Xen with dom0 in single-user mode:load /netbsd-XEN3_DOM0 -s;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M
menu=Go to command line (advanced users only):prompt
clear=1
timeout=-1
default=1
userconf=disable ehci*
# Always load ramdisk module
load=/miniroot.kmod
N.B. Xen counts serial ports from com1 upwards, but
NetBSD counts from com0, so the appropriate device
name must be used. Please see the Xen with serial console example above.
This will clear the screen and display:
Welcome to NetBSD
=================
Please choose an option from the following menu:
1. Boot normally
2. Boot single-user
3. Boot from second disk
4. Boot with module foo
5. Boot with modules foo and bar
6. Boot Xen with 256 MB for dom0
7. Boot Xen with 256 MB for dom0 (serial)
8. Boot Xen with dom0 in single-user mode
9. Go to command line (advanced users only)
Option [1]:
It will then wait for the user to type 1, 2, 3, 4, 5, 6, 7, 8 or 9 followed by
Return. Pressing Return by itself will run option 1. There will be no timeout.
SEE ALSO
boot(8),
boothowto(9)
HISTORY
The
boot.cfg file appeared in
NetBSD
5.0.
AUTHORS
The
boot.cfg extensions to
boot(8) were written by
Stephen Borrill ⟨sborrill@NetBSD.org⟩.
BUGS
Support for
boot.cfg is currently for
NetBSD/i386 and
NetBSD/amd64
only. It is hoped that its use will be extended to other appropriate ports
that use the
boot(8)
interface.