1.\" $NetBSD: boot.cfg.5,v 1.24 2011/11/28 09:38:45 wiz Exp $ 2.\" 3.\" Copyright (c) 2007 Stephen Borrill 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd November 28, 2011 29.Dt BOOT.CFG 5 30.Os 31.Sh NAME 32.Nm boot.cfg 33.Nd configuration file for /boot 34.Sh DESCRIPTION 35The file 36.Pa /boot.cfg 37is used to alter the behaviour of the standard boot loader described in 38.Xr boot 8 . 39Configuration changes include setting the timeout, choosing a console device, 40altering the banner text and displaying a menu allowing boot commands to be 41easily chosen. 42If a 43.Nm 44file is not present, the system will boot as normal. 45.Ss FILE FORMAT 46The format of the file is a series of lines containing keyword/value pairs 47separated by an equals sign 48.Pq Sq = . 49There should be no whitespace surrounding the equals sign. 50Lines beginning with a hash 51.Pq Sq # 52are comments and will be ignored. 53.Pp 54Some keywords can be present multiple times in the file to define additional 55items. 56Such keywords are noted below. 57.Pp 58.Bl -tag -width timeout 59.It Sy banner 60(may be present multiple times) 61The text from banner lines is displayed instead of the standard welcome text 62by the boot loader. 63Up to 10 lines can be defined. 64No special character sequences are recognised, so to specify a blank line, a 65banner line with no value should be given. 66.It Sy clear 67If nonzero, clear the screen before printing the banner. 68If zero, do not clear the screen (the default). 69.It Sy consdev 70Changes the console device to that specified in the value. 71Valid values are any of those that could be specified at the normal boot 72prompt with the consdev command. 73.It Sy default 74Used to specify the default menu item which will be chosen in the case of 75Return being pressed or the timeout timer reaching zero. 76The value is the number of the menu item as displayed. 77As described above, the menu items are counted from 1 in the order listed in 78.Nm . 79If not specified, the default value will be option 1, i.e. the first item. 80.It Sy format 81Changes how the menu options are displayed. 82Should be set to one of 83.Sq a 84for automatic, 85.Sq l 86for letters and 87.Sq n 88for numbers. 89If set to automatic (the default), menu options will be displayed numerically 90unless there are more than 9 options and the timeout is greater than zero. 91If there are more than 9 options with a timeout greater than zero and 92the format is set to number, only the first 9 options will be available. 93.It Sy load 94Used to load kernel modules, which will be passed on to the kernel for 95initialization during early boot. 96The argument is either the complete path and file name of the module to be 97loaded, or a symbolic module name. 98When the argument is not an absolute path, the boot loader will first 99attempt to load 100.Pa /stand/\*[Lt]machine\*[Gt]/\*[Lt]kernel_version\*[Gt]/modules/\*[Lt]name\*[Gt]/\*[Lt]name\*[Gt].kmod . 101If that file does not exist, it will then attempt to load 102.Pa /\*[Lt]name\*[Gt] . 103May be used as many times as needed. 104.It Sy menu 105(may be present multiple times) 106Used to define a menu item to be displayed to the end-user at boot time 107which allows a series of boot commands to be run without further typing. 108The value consists of the required menu text, followed by a colon 109.Pq Sq \&: 110and then the desired command(s). 111Multiple commands can be specified separated by a semi-colon. 112If the specified menu text is empty 113(the colon appears immediately after the equals sign), 114then the displayed menu text is the same as the command. 115For example: 116.Bd -literal 117menu=Boot normally:boot 118menu=Boot single-user:boot -s 119menu=Boot with module foo:load /foo.kmod;boot 120menu=Boot with serial console:consdev com0;boot 121menu=:boot hd1a:netbsd -as 122.Ed 123.Pp 124Each menu item will be prefixed by an ascending number when displayed, 125i.e. the order in the 126.Nm 127file is important. 128.Pp 129Each command is executed just as though the user had typed it in 130and so can be any valid command that would be accepted at the 131normal boot prompt. 132In addition, 133.Dq Ic edit 134can be used to put the menu in editing mode, allowing the user to modify the 135next selected option before executing it, and 136.Dq Ic prompt 137can be used to drop to the normal boot prompt. 138.It Sy timeout 139If the value is greater than zero, this specifies the time in seconds 140that the boot loader will wait for the end-user to choose a menu item. 141During the countdown period, they may press Return to choose the default 142option or press a number key corresponding to a menu option. 143If any other key is pressed, the countdown will stop and the user will be 144prompted to choose a menu option with no further time limit. 145If the timeout value is set to zero, the default option will be booted 146immediately. 147If the timeout value is negative or is not a number, there will be no 148time limit for the user to choose an option. 149.It Sy userconf 150Passes a 151.Xr userconf 4 152command to the kernel at boot time . 153.It Sy rndseed 154Takes the path to a random-seed file as written by the 155.Fl S 156flag to 157.Xr rndctl 8 158as an argument. 159This file is used to seed the kernel entropy pool 160.Xr rnd 9 161very early in kernel startup, so that high quality randomness is 162available to all kernel modules. 163This argument should be supplied 164before any 165.Dq Ic load 166commands that may load executable modules. 167.El 168.Sh EXAMPLES 169Here is an example 170.Nm 171file: 172.Bd -literal -offset indent 173banner=Welcome to NetBSD 174banner================== 175banner= 176banner=Please choose an option from the following menu: 177menu=Boot normally:boot 178menu=Boot single-user:boot -s 179menu=Boot from second disk:boot hd1a: 180menu=Boot with module foo:load /foo.kmod;boot 181menu=Boot with modules foo and bar:load /foo.kmod;load /bar.kmod;boot 182menu=Boot Xen with 256MB for dom0:load /netbsd-XEN3_DOM0 console=pc;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M 183menu=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 184menu=Boot Xen with dom0 in single-user mode:load /netbsd-XEN3_DOM0 -s;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M 185menu=Go to command line (advanced users only):prompt 186clear=1 187timeout=-1 188default=1 189userconf disable ehci* 190# Always load ramdisk module 191load=/miniroot.kmod 192.Ed 193.Pp 194N.B. Xen counts serial ports from com1 upwards, but 195.Nx 196counts from com0, so the appropriate device name must be used. 197Please see the Xen with serial console example above. 198.Pp 199This will clear the screen and display: 200.Bd -literal -offset indent 201Welcome to NetBSD 202================= 203 204Please choose an option from the following menu: 205 206 1. Boot normally 207 2. Boot single-user 208 3. Boot from second disk 209 4. Boot with module foo 210 5. Boot with modules foo and bar 211 6. Boot Xen with 256 MB for dom0 212 7. Boot Xen with 256 MB for dom0 (serial) 213 8. Boot Xen with dom0 in single-user mode 214 9. Go to command line (advanced users only) 215 216Option [1]: 217.Ed 218.Pp 219It will then wait for the user to type 1, 2, 3, 4, 5, 6, 7, 8 or 9 followed by 220Return. 221Pressing Return by itself will run option 1. 222There will be no timeout. 223.Sh SEE ALSO 224.Xr boot 8 , 225.Xr boothowto 9 226.Sh HISTORY 227The 228.Nm 229file appeared in 230.Nx 5.0 . 231.Sh AUTHORS 232The 233.Nm 234extensions to 235.Xr boot 8 236were written by 237.An Stephen Borrill 238.Aq sborrill@NetBSD.org . 239.Sh BUGS 240Support for 241.Nm 242is currently for 243.Nx Ns /i386 244and 245.Nx Ns /amd64 246only. 247It is hoped that its use will be extended to other appropriate ports that 248use the 249.Xr boot 8 250interface. 251