1.\" $NetBSD: boot.cfg.5,v 1.5 2008/05/02 15:26:38 ad 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. 72If the specified menu text is empty 73(the colon appears immediately after the equals sign), 74then the displayed menu text is the same as the command. 75For example: 76.Bd -literal 77menu=Boot normally:boot 78menu=Boot single-user:boot -s 79menu=:boot hd1a:netbsd -as 80.Ed 81.Pp 82Each menu item will be prefixed by an ascending number when displayed, 83i.e. the order in the 84.Nm 85file is important. 86.Pp 87The command is executed just as though the user had typed it in 88and so can be any valid command that would be accepted at the 89normal boot prompt. 90In addition, 91.So prompt Sc 92can be used to drop to the normal boot prompt. 93.It Sy timeout 94If the value is greater than zero, this specifies the time in seconds 95that the boot loader will wait for the end-user to choose a menu item. 96During the countdown period, they may press Return to choose the default 97option or press a number key corresponding to a menu option. 98If any other key is pressed, the countdown will stop and the user will be 99prompted to choose a menu option with no further time limit. 100If the timeout value is set to zero, the default option will be booted 101immediately. 102If the timeout value is negative or is not a number, there will be no 103time limit for the user to choose an option. 104.It Sy default 105Used to specify the default menu item which will be chosen in the case of 106Return being pressed or the timeout timer reaching zero. 107The value is the number of the menu item as displayed. 108As described above, the menu items are counted from 1 in the order listed in 109.Nm . 110If not specified, the default value will be option 1, i.e. the first item. 111.It Sy consdev 112Changes the console device to that specified in the value. 113Valid values are any of those that could be specified at the normal boot 114prompt with the consdev command. 115.It Sy load 116Used to load kernel modules, which will be passed on to the kernel for 117initialization during early boot. 118The argument is the complete path and file name of the module to be loaded. 119May be used as many times as needed. 120.El 121.Sh EXAMPLES 122Here is an example 123.Nm 124file: 125.Bd -literal -offset indent 126banner=Welcome to NetBSD 127banner================== 128banner= 129banner=Please choose an option from the following menu: 130menu=Boot normally:boot 131menu=Boot single-user:boot -s 132menu=Boot from second disk:boot hd1a: 133menu=Go to command line (advanced users only):prompt 134timeout=-1 135default=1 136load=/ramdisk.kmod 137.Ed 138.Pp 139This will display: 140.Bd -literal -offset indent 141Welcome to NetBSD 142================= 143 144Please choose an option from the following menu: 145 146 1. Boot normally 147 2. Boot single-user 148 3. Boot from second disk 149 4. Go to command line (advanced users only) 150 151Option [1]: 152.Ed 153.Pp 154It will then wait for the user to type 1, 2, 3 or 4 followed by Return. 155Pressing Return by itself will run option 1. 156There will be no timeout. 157.Sh SEE ALSO 158.Xr boot 8 159.Sh BUGS 160Support for 161.Nm 162is currently for 163.Nx Ns /i386 and 164.Nx Ns /amd64 only. 165It is hoped that its use will be extended to other appropriate ports that 166use the 167.Xr boot 8 168interface. 169.Sh HISTORY 170The 171.Nm 172utility appeared in 173.Nx 5.0 . 174.Sh AUTHORS 175The 176.Nm 177extensions to 178.Xr boot 8 179were written by 180.An Stephen Borrill 181.Aq sborrill@NetBSD.org . 182