man/man5/boot.cfg.5

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