1.\" $NetBSD: boot.cfg.5,v 1.4 2008/01/05 19:29:16 apb 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 19, 2007 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.El 116.Sh EXAMPLES 117Here is an example 118.Nm 119file: 120.Bd -literal -offset indent 121banner=Welcome to NetBSD 122banner================== 123banner= 124banner=Please choose an option from the following menu: 125menu=Boot normally:boot 126menu=Boot single-user:boot -s 127menu=Boot from second disk:boot hd1a: 128menu=Go to command line (advanced users only):prompt 129timeout=-1 130default=1 131.Ed 132.Pp 133This will display: 134.Bd -literal -offset indent 135Welcome to NetBSD 136================= 137 138Please choose an option from the following menu: 139 140 1. Boot normally 141 2. Boot single-user 142 3. Boot from second disk 143 4. Go to command line (advanced users only) 144 145Option [1]: 146.Ed 147.Pp 148It will then wait for the user to type 1, 2, 3 or 4 followed by Return. 149Pressing Return by itself will run option 1. 150There will be no timeout. 151.Sh SEE ALSO 152.Xr boot 8 153.Sh BUGS 154Support for 155.Nm 156is currently for 157.Nx Ns /i386 and 158.Nx Ns /amd64 only. 159It is hoped that its use will be extended to other appropriate ports that 160use the 161.Xr boot 8 162interface. 163.Sh HISTORY 164The 165.Nm 166utility appeared in 167.Nx 5.0 . 168.Sh AUTHORS 169The 170.Nm 171extensions to 172.Xr boot 8 173were written by 174.An Stephen Borrill 175.Aq sborrill@NetBSD.org . 176