1.\" $NetBSD: boot.cfg.5,v 1.7 2008/05/03 20:19:02 sborrill 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 May 2, 2008 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 /boot.cfg 36is used to alter the behaviour of the standard boot loader described in 37.Xr boot 8 . 38Configuration changes include setting the timeout, choosing a console device, 39altering the banner text and displaying a menu allowing boot commands to be 40easily chosen. 41If a 42.Nm 43file is not present, the system will boot as normal. 44.Ss FILE FORMAT 45The format of the file is a series of lines containing keyword/value pairs 46separated by an equals sign 47.Pq Sq = . 48There should be no whitespace surrounding the equals sign. 49Lines beginning with a hash 50.Pq Sq # 51are comments and will be ignored. 52.Pp 53Some keywords can be present multiple times in the file to define additional 54items. 55Such keywords are noted below. 56.Pp 57.Bl -tag -width timeout 58.It Sy banner 59(may be present multiple times) 60The text from banner lines is displayed instead of the standard welcome text 61by the boot loader. 62Up to 10 lines can be defined. 63No special character sequences are recognised, so to specify a blank line, a 64banner line with no value should be given. 65.It Sy menu 66(may be present multiple times) 67Used to define a menu item to be displayed to the end-user at boot time 68which allows a series of boot commands to be run without further typing. 69The value consists of the required menu text, followed by a colon 70.Pq Sq \&: 71and then the desired command(s). 72Multiple commands can be specified separated by a semi-colon. 73If the specified menu text is empty 74(the colon appears immediately after the equals sign), 75then the displayed menu text is the same as the command. 76For example: 77.Bd -literal 78menu=Boot normally:boot 79menu=Boot single-user:boot -s 80menu=Boot with module foo:load /foo.kmod;boot 81menu=Boot with serial console:consdev com0;boot 82menu=:boot hd1a:netbsd -as 83.Ed 84.Pp 85Each menu item will be prefixed by an ascending number when displayed, 86i.e. the order in the 87.Nm 88file is important. 89.Pp 90Each command is executed just as though the user had typed it in 91and so can be any valid command that would be accepted at the 92normal boot prompt. 93In addition, 94.So prompt Sc 95can be used to drop to the normal boot prompt. 96.It Sy timeout 97If the value is greater than zero, this specifies the time in seconds 98that the boot loader will wait for the end-user to choose a menu item. 99During the countdown period, they may press Return to choose the default 100option or press a number key corresponding to a menu option. 101If any other key is pressed, the countdown will stop and the user will be 102prompted to choose a menu option with no further time limit. 103If the timeout value is set to zero, the default option will be booted 104immediately. 105If the timeout value is negative or is not a number, there will be no 106time limit for the user to choose an option. 107.It Sy default 108Used to specify the default menu item which will be chosen in the case of 109Return being pressed or the timeout timer reaching zero. 110The value is the number of the menu item as displayed. 111As described above, the menu items are counted from 1 in the order listed in 112.Nm . 113If not specified, the default value will be option 1, i.e. the first item. 114.It Sy consdev 115Changes the console device to that specified in the value. 116Valid values are any of those that could be specified at the normal boot 117prompt with the consdev command. 118.It Sy load 119Used to load kernel modules, which will be passed on to the kernel for 120initialization during early boot. 121The argument is the complete path and file name of the module to be loaded. 122May be used as many times as needed. 123.El 124.Sh EXAMPLES 125Here is an example 126.Nm 127file: 128.Bd -literal -offset indent 129banner=Welcome to NetBSD 130banner================== 131banner= 132banner=Please choose an option from the following menu: 133menu=Boot normally:boot 134menu=Boot single-user:boot -s 135menu=Boot from second disk:boot hd1a: 136menu=Boot with module foo:load /foo.kmod;boot 137menu=Boot with modules foo and bar:load /foo.kmod;load /bar.kmod;boot 138menu=Go to command line (advanced users only):prompt 139timeout=-1 140default=1 141# Always load ramdisk module 142load=/ramdisk.kmod 143.Ed 144.Pp 145This will display: 146.Bd -literal -offset indent 147Welcome to NetBSD 148================= 149 150Please choose an option from the following menu: 151 152 1. Boot normally 153 2. Boot single-user 154 3. Boot from second disk 155 4. Boot with module foo 156 5. Boot with modules foo and bar 157 6. Go to command line (advanced users only) 158 159Option [1]: 160.Ed 161.Pp 162It will then wait for the user to type 1, 2, 3, 4, 5 or 6 followed by Return. 163Pressing Return by itself will run option 1. 164There will be no timeout. 165.Sh SEE ALSO 166.Xr boot 8 167.Sh BUGS 168Support for 169.Nm 170is currently for 171.Nx Ns /i386 and 172.Nx Ns /amd64 only. 173It is hoped that its use will be extended to other appropriate ports that 174use the 175.Xr boot 8 176interface. 177.Sh HISTORY 178The 179.Nm 180utility appeared in 181.Nx 5.0 . 182.Sh AUTHORS 183The 184.Nm 185extensions to 186.Xr boot 8 187were written by 188.An Stephen Borrill 189.Aq sborrill@NetBSD.org . 190