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