Annotation of src/share/man/man5/boot.cfg.5, Revision 1.4.6.2
1.4.6.1 mjf 1: .\" $NetBSD$
1.1 sborrill 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: .\"
1.4.6.2 ! mjf 28: .Dd August 13, 2008
1.2 sborrill 29: .Dt BOOT.CFG 5
1.1 sborrill 30: .Os
31: .Sh NAME
32: .Nm boot.cfg
33: .Nd configuration file for /boot
34: .Sh DESCRIPTION
1.4.6.2 ! mjf 35: The file
! 36: .Pa /boot.cfg
1.1 sborrill 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 menu
67: (may be present multiple times)
68: Used to define a menu item to be displayed to the end-user at boot time
69: which allows a series of boot commands to be run without further typing.
70: The value consists of the required menu text, followed by a colon
1.4 apb 71: .Pq Sq \&:
1.4.6.1 mjf 72: and then the desired command(s).
73: Multiple commands can be specified separated by a semi-colon.
1.4 apb 74: If the specified menu text is empty
75: (the colon appears immediately after the equals sign),
76: then the displayed menu text is the same as the command.
1.1 sborrill 77: For example:
78: .Bd -literal
79: menu=Boot normally:boot
80: menu=Boot single-user:boot -s
1.4.6.1 mjf 81: menu=Boot with module foo:load /foo.kmod;boot
82: menu=Boot with serial console:consdev com0;boot
1.4 apb 83: menu=:boot hd1a:netbsd -as
1.1 sborrill 84: .Ed
85: .Pp
86: Each menu item will be prefixed by an ascending number when displayed,
87: i.e. the order in the
88: .Nm
89: file is important.
90: .Pp
1.4.6.1 mjf 91: Each command is executed just as though the user had typed it in
1.1 sborrill 92: and so can be any valid command that would be accepted at the
93: normal boot prompt.
94: In addition,
1.4.6.2 ! mjf 95: .Dq Ic prompt
1.1 sborrill 96: can be used to drop to the normal boot prompt.
97: .It Sy timeout
98: If the value is greater than zero, this specifies the time in seconds
99: that the boot loader will wait for the end-user to choose a menu item.
100: During the countdown period, they may press Return to choose the default
101: option or press a number key corresponding to a menu option.
102: If any other key is pressed, the countdown will stop and the user will be
103: prompted to choose a menu option with no further time limit.
104: If the timeout value is set to zero, the default option will be booted
105: immediately.
106: If the timeout value is negative or is not a number, there will be no
107: time limit for the user to choose an option.
108: .It Sy default
109: Used to specify the default menu item which will be chosen in the case of
110: Return being pressed or the timeout timer reaching zero.
111: The value is the number of the menu item as displayed.
112: As described above, the menu items are counted from 1 in the order listed in
113: .Nm .
114: If not specified, the default value will be option 1, i.e. the first item.
115: .It Sy consdev
116: Changes the console device to that specified in the value.
117: Valid values are any of those that could be specified at the normal boot
118: prompt with the consdev command.
1.4.6.1 mjf 119: .It Sy load
120: Used to load kernel modules, which will be passed on to the kernel for
121: initialization during early boot.
122: The argument is the complete path and file name of the module to be loaded.
123: May be used as many times as needed.
1.4.6.2 ! mjf 124: .It Sy format
! 125: Changes how the menu options are displayed.
! 126: Should be set to one of
! 127: .Sq a
! 128: for automatic,
! 129: .Sq l
! 130: for letters and
! 131: .Sq n
! 132: for numbers.
! 133: If set to automatic (the default), menu options will be displayed numerically
! 134: unless there are more than 9 options and the timeout is greater than zero.
! 135: If there are more than 9 options with a timeout greater than zero and
! 136: the format is set to number, only the first 9 options will be available.
1.1 sborrill 137: .El
138: .Sh EXAMPLES
139: Here is an example
140: .Nm
141: file:
142: .Bd -literal -offset indent
143: banner=Welcome to NetBSD
144: banner==================
145: banner=
146: banner=Please choose an option from the following menu:
147: menu=Boot normally:boot
148: menu=Boot single-user:boot -s
149: menu=Boot from second disk:boot hd1a:
1.4.6.1 mjf 150: menu=Boot with module foo:load /foo.kmod;boot
151: menu=Boot with modules foo and bar:load /foo.kmod;load /bar.kmod;boot
1.1 sborrill 152: menu=Go to command line (advanced users only):prompt
153: timeout=-1
154: default=1
1.4.6.1 mjf 155: # Always load ramdisk module
156: load=/ramdisk.kmod
1.1 sborrill 157: .Ed
158: .Pp
159: This will display:
160: .Bd -literal -offset indent
161: Welcome to NetBSD
162: =================
163:
164: Please choose an option from the following menu:
165:
166: 1. Boot normally
167: 2. Boot single-user
168: 3. Boot from second disk
1.4.6.1 mjf 169: 4. Boot with module foo
170: 5. Boot with modules foo and bar
171: 6. Go to command line (advanced users only)
1.1 sborrill 172:
173: Option [1]:
174: .Ed
175: .Pp
1.4.6.2 ! mjf 176: It will then wait for the user to type 1, 2, 3, 4, 5, or 6 followed by Return.
1.1 sborrill 177: Pressing Return by itself will run option 1.
178: There will be no timeout.
179: .Sh SEE ALSO
180: .Xr boot 8
181: .Sh HISTORY
182: The
183: .Nm
184: utility appeared in
185: .Nx 5.0 .
186: .Sh AUTHORS
187: The
188: .Nm
189: extensions to
190: .Xr boot 8
191: were written by
192: .An Stephen Borrill
193: .Aq sborrill@NetBSD.org .
1.4.6.2 ! mjf 194: .Sh BUGS
! 195: Support for
! 196: .Nm
! 197: is currently for
! 198: .Nx Ns /i386
! 199: and
! 200: .Nx Ns /amd64
! 201: only.
! 202: It is hoped that its use will be extended to other appropriate ports that
! 203: use the
! 204: .Xr boot 8
! 205: interface.
CVSweb <webmaster@jp.NetBSD.org>