1.\" $NetBSD: boot.cfg.5,v 1.32 2022/04/15 16:30:09 fcambus 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 24, 2020 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 54The 55.Dq Ic banner , 56.Dq Ic load , 57.Dq Ic menu , 58and 59.Dq Ic userconf 60keywords can be present multiple times in the file to define additional 61items. 62See the description for each keyword for guidance and limitations on 63using multiple entries. 64.Bl -tag -width timeout 65.It Sy banner 66The text from banner lines is displayed instead of the standard welcome text 67by the boot loader. 68Up to 12 lines can be defined. 69No special character sequences are recognised, so to specify a blank line, a 70banner line with no value should be given. 71.It Sy clear 72If nonzero, clear the screen before printing the banner. 73If zero, do not clear the screen (the default). 74.It Sy consdev 75Changes the console device to that specified in the value. 76Valid values are any of those that could be specified at the normal boot 77prompt with the consdev command. 78.It Sy default 79Used to specify the default menu item which will be chosen in the case of 80Return being pressed or the timeout timer reaching zero. 81The value is the number of the menu item as displayed. 82As described above, the menu items are counted from 1 in the order listed in 83.Nm . 84If not specified, the default value will be option 1, i.e. the first item. 85.It Sy format 86Changes how the menu options are displayed. 87Should be set to one of 88.Sq a 89for automatic, 90.Sq l 91for letters and 92.Sq n 93for numbers. 94If set to automatic (the default), menu options will be displayed numerically 95unless there are more than 9 options and the timeout is greater than zero. 96If there are more than 9 options with a timeout greater than zero and 97the format is set to number, only the first 9 options will be available. 98.It Sy load 99Used to load kernel modules, which will be passed on to the kernel for 100initialization during early boot. 101The argument is either the complete path and file name of the module to be 102loaded, or a symbolic module name. 103When the argument is not an absolute path, the boot loader will first 104attempt to load 105.Pa /stand/<machine>/<kernel_version>/modules/<name>/<name>.kmod . 106If that file does not exist, it will then attempt to load 107.Pa /<name> . 108May be used as many times as needed. 109.It Sy menu 110Used to define a menu item to be displayed to the end-user at boot time 111which allows a series of boot commands to be run without further typing. 112The value consists of the required menu text, followed by a colon 113.Pq Sq \&: 114and then the desired command(s). 115Multiple commands can be specified separated by a semi-colon. 116If the specified menu text is empty 117(the colon appears immediately after the equals sign), 118then the displayed menu text is the same as the command. 119For example: 120.Bd -literal 121menu=Boot normally:boot 122menu=Boot single-user:boot -s 123menu=Boot with module foo:load /foo.kmod;boot 124menu=Boot with serial console:consdev com0;boot 125menu=:boot hd1a:netbsd -as 126.Ed 127.Pp 128Each menu item will be prefixed by an ascending number when displayed, 129i.e. the order in the 130.Nm 131file is important. 132.Pp 133Each command is executed just as though the user had typed it in 134and so can be any valid command that would be accepted at the 135normal boot prompt. 136In addition, 137.Dq Ic prompt 138can be used to drop to the normal boot prompt. 139.It Sy rndseed 140Takes the path to a random-seed file as written by the 141.Fl S 142flag to 143.Xr rndctl 8 144as an argument. 145This file is used to seed the kernel entropy pool 146.Xr rnd 9 147very early in kernel startup, so that high quality randomness is 148available to all kernel modules. 149This argument should be supplied 150before any 151.Dq Ic load 152commands that may load executable modules. 153.It Sy timeout 154If the value is greater than zero, this specifies the time in seconds 155that the boot loader will wait for the end-user to choose a menu item. 156During the countdown period, they may press Return to choose the default 157option or press a number key corresponding to a menu option. 158If any other key is pressed, the countdown will stop and the user will be 159prompted to choose a menu option with no further time limit. 160If the timeout value is set to zero, the default option will be booted 161immediately. 162If the timeout value is negative or is not a number, there will be no 163time limit for the user to choose an option. 164.It Sy userconf 165Passes a 166.Xr userconf 4 167command to the kernel at boot time. 168May be used as many times as needed. 169.El 170.Sh EXAMPLES 171Here is an example 172.Nm 173file: 174.Bd -literal -offset indent 175banner=Welcome to NetBSD 176banner================== 177banner= 178banner=Please choose an option from the following menu: 179menu=Boot normally:boot 180menu=Boot single-user:boot -s 181menu=Boot from second disk:boot hd1a: 182menu=Boot with module foo:load /foo.kmod;boot 183menu=Boot with modules foo and bar:load /foo.kmod;load /bar.kmod;boot 184menu=Boot Xen with 256MB for dom0:load /netbsd-XEN3_DOM0 console=pc;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M 185menu=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 186menu=Boot Xen with dom0 in single-user mode:load /netbsd-XEN3_DOM0 -s;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M 187menu=Go to command line (advanced users only):prompt 188clear=1 189timeout=-1 190default=1 191# Disable Direct Rendering Manager (DRM) drivers 192userconf=disable i915drmkms* 193userconf=disable nouveau* 194userconf=disable radeon* 195# Always load ramdisk module 196load=/miniroot.kmod 197.Ed 198.Pp 199N.B. Xen counts serial ports from com1 upwards, but 200.Nx 201counts from com0, so the appropriate device name must be used. 202Please see the Xen with serial console example above. 203.Pp 204This will clear the screen and display: 205.Bd -literal -offset indent 206Welcome to NetBSD 207================= 208 209Please choose an option from the following menu: 210 211 1. Boot normally 212 2. Boot single-user 213 3. Boot from second disk 214 4. Boot with module foo 215 5. Boot with modules foo and bar 216 6. Boot Xen with 256 MB for dom0 217 7. Boot Xen with 256 MB for dom0 (serial) 218 8. Boot Xen with dom0 in single-user mode 219 9. Go to command line (advanced users only) 220 221Option [1]: 222.Ed 223.Pp 224It will then wait for the user to type 1, 2, 3, 4, 5, 6, 7, 8 or 9 followed by 225Return. 226Pressing Return by itself will run option 1. 227There will be no timeout. 228.Sh SEE ALSO 229.Xr boot 8 , 230.Xr boothowto 9 231.Sh HISTORY 232The 233.Nm 234file appeared in 235.Nx 5.0 . 236.Sh AUTHORS 237The 238.Nm 239extensions to 240.Xr boot 8 241were written by 242.An Stephen Borrill 243.Aq sborrill@NetBSD.org . 244.Sh BUGS 245Support for 246.Nm 247is currently for 248.Nx Ns /i386 249and 250.Nx Ns /amd64 251only. 252It is hoped that its use will be extended to other appropriate ports that 253use the 254.Xr boot 8 255interface. 256