Thu Oct 28 14:29:18 2010 UTC ()
Correct section in xref.


(jruoho)
diff -r1.20 -r1.21 src/share/man/man5/boot.cfg.5
cvs diff -r1.20 -r1.21 src/share/man/man5/boot.cfg.5 (switch to unified diff)

--- src/share/man/man5/boot.cfg.5 2010/10/28 09:49:01 1.20
+++ src/share/man/man5/boot.cfg.5 2010/10/28 14:29:18 1.21
@@ -1,228 +1,228 @@ @@ -1,228 +1,228 @@
1.\" $NetBSD: boot.cfg.5,v 1.20 2010/10/28 09:49:01 jruoho Exp $ 1.\" $NetBSD: boot.cfg.5,v 1.21 2010/10/28 14:29:18 jruoho Exp $
2.\" 2.\"
3.\" Copyright (c) 2007 Stephen Borrill 3.\" Copyright (c) 2007 Stephen Borrill
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 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 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 15.\" derived from this software without specific prior written permission
16.\" 16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 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 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 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 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 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 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. 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27.\" 27.\"
28.Dd October 28, 2010 28.Dd October 28, 2010
29.Dt BOOT.CFG 5 29.Dt BOOT.CFG 5
30.Os 30.Os
31.Sh NAME 31.Sh NAME
32.Nm boot.cfg 32.Nm boot.cfg
33.Nd configuration file for /boot 33.Nd configuration file for /boot
34.Sh DESCRIPTION 34.Sh DESCRIPTION
35The file 35The file
36.Pa /boot.cfg 36.Pa /boot.cfg
37is used to alter the behaviour of the standard boot loader described in 37is used to alter the behaviour of the standard boot loader described in
38.Xr boot 8 . 38.Xr boot 8 .
39Configuration changes include setting the timeout, choosing a console device, 39Configuration changes include setting the timeout, choosing a console device,
40altering the banner text and displaying a menu allowing boot commands to be 40altering the banner text and displaying a menu allowing boot commands to be
41easily chosen. 41easily chosen.
42If a 42If a
43.Nm 43.Nm
44file is not present, the system will boot as normal. 44file is not present, the system will boot as normal.
45.Ss FILE FORMAT 45.Ss FILE FORMAT
46The format of the file is a series of lines containing keyword/value pairs 46The format of the file is a series of lines containing keyword/value pairs
47separated by an equals sign 47separated by an equals sign
48.Pq Sq = . 48.Pq Sq = .
49There should be no whitespace surrounding the equals sign. 49There should be no whitespace surrounding the equals sign.
50Lines beginning with a hash 50Lines beginning with a hash
51.Pq Sq # 51.Pq Sq #
52are comments and will be ignored. 52are comments and will be ignored.
53.Pp 53.Pp
54Some keywords can be present multiple times in the file to define additional 54Some keywords can be present multiple times in the file to define additional
55items. 55items.
56Such keywords are noted below. 56Such keywords are noted below.
57.Pp 57.Pp
58.Bl -tag -width timeout 58.Bl -tag -width timeout
59.It Sy banner 59.It Sy banner
60(may be present multiple times) 60(may be present multiple times)
61The text from banner lines is displayed instead of the standard welcome text 61The text from banner lines is displayed instead of the standard welcome text
62by the boot loader. 62by the boot loader.
63Up to 10 lines can be defined. 63Up to 10 lines can be defined.
64No special character sequences are recognised, so to specify a blank line, a 64No special character sequences are recognised, so to specify a blank line, a
65banner line with no value should be given. 65banner line with no value should be given.
66.It Sy clear 66.It Sy clear
67If nonzero, clear the screen before printing the banner. 67If nonzero, clear the screen before printing the banner.
68If zero, do not clear the screen (the default). 68If zero, do not clear the screen (the default).
69.It Sy consdev 69.It Sy consdev
70Changes the console device to that specified in the value. 70Changes the console device to that specified in the value.
71Valid values are any of those that could be specified at the normal boot 71Valid values are any of those that could be specified at the normal boot
72prompt with the consdev command. 72prompt with the consdev command.
73.It Sy default 73.It Sy default
74Used to specify the default menu item which will be chosen in the case of 74Used to specify the default menu item which will be chosen in the case of
75Return being pressed or the timeout timer reaching zero. 75Return being pressed or the timeout timer reaching zero.
76The value is the number of the menu item as displayed. 76The value is the number of the menu item as displayed.
77As described above, the menu items are counted from 1 in the order listed in 77As described above, the menu items are counted from 1 in the order listed in
78.Nm . 78.Nm .
79If not specified, the default value will be option 1, i.e. the first item. 79If not specified, the default value will be option 1, i.e. the first item.
80.It Sy format 80.It Sy format
81Changes how the menu options are displayed. 81Changes how the menu options are displayed.
82Should be set to one of 82Should be set to one of
83.Sq a 83.Sq a
84for automatic, 84for automatic,
85.Sq l 85.Sq l
86for letters and 86for letters and
87.Sq n 87.Sq n
88for numbers. 88for numbers.
89If set to automatic (the default), menu options will be displayed numerically 89If set to automatic (the default), menu options will be displayed numerically
90unless there are more than 9 options and the timeout is greater than zero. 90unless there are more than 9 options and the timeout is greater than zero.
91If there are more than 9 options with a timeout greater than zero and 91If there are more than 9 options with a timeout greater than zero and
92the format is set to number, only the first 9 options will be available. 92the format is set to number, only the first 9 options will be available.
93.It Sy load 93.It Sy load
94Used to load kernel modules, which will be passed on to the kernel for 94Used to load kernel modules, which will be passed on to the kernel for
95initialization during early boot. 95initialization during early boot.
96The argument is either the complete path and file name of the module to be 96The argument is either the complete path and file name of the module to be
97loaded, or a symbolic module name. 97loaded, or a symbolic module name.
98When the argument is not an absolute path, the boot loader will first 98When the argument is not an absolute path, the boot loader will first
99attempt to load 99attempt to load
100.Pa /stand/\*[Lt]machine\*[Gt]/\*[Lt]kernel_version\*[Gt]/modules/\*[Lt]name\*[Gt]/\*[Lt]name\*[Gt].kmod . 100.Pa /stand/\*[Lt]machine\*[Gt]/\*[Lt]kernel_version\*[Gt]/modules/\*[Lt]name\*[Gt]/\*[Lt]name\*[Gt].kmod .
101If that file does not exist, it will then attempt to load 101If that file does not exist, it will then attempt to load
102.Pa /\*[Lt]name\*[Gt] . 102.Pa /\*[Lt]name\*[Gt] .
103May be used as many times as needed. 103May be used as many times as needed.
104.It Sy menu 104.It Sy menu
105(may be present multiple times) 105(may be present multiple times)
106Used to define a menu item to be displayed to the end-user at boot time 106Used to define a menu item to be displayed to the end-user at boot time
107which allows a series of boot commands to be run without further typing. 107which allows a series of boot commands to be run without further typing.
108The value consists of the required menu text, followed by a colon 108The value consists of the required menu text, followed by a colon
109.Pq Sq \&: 109.Pq Sq \&:
110and then the desired command(s). 110and then the desired command(s).
111Multiple commands can be specified separated by a semi-colon. 111Multiple commands can be specified separated by a semi-colon.
112If the specified menu text is empty 112If the specified menu text is empty
113(the colon appears immediately after the equals sign), 113(the colon appears immediately after the equals sign),
114then the displayed menu text is the same as the command. 114then the displayed menu text is the same as the command.
115For example: 115For example:
116.Bd -literal 116.Bd -literal
117menu=Boot normally:boot 117menu=Boot normally:boot
118menu=Boot single-user:boot -s 118menu=Boot single-user:boot -s
119menu=Boot with module foo:load /foo.kmod;boot 119menu=Boot with module foo:load /foo.kmod;boot
120menu=Boot with serial console:consdev com0;boot 120menu=Boot with serial console:consdev com0;boot
121menu=:boot hd1a:netbsd -as 121menu=:boot hd1a:netbsd -as
122.Ed 122.Ed
123.Pp 123.Pp
124Each menu item will be prefixed by an ascending number when displayed, 124Each menu item will be prefixed by an ascending number when displayed,
125i.e. the order in the 125i.e. the order in the
126.Nm 126.Nm
127file is important. 127file is important.
128.Pp 128.Pp
129Each command is executed just as though the user had typed it in 129Each command is executed just as though the user had typed it in
130and so can be any valid command that would be accepted at the 130and so can be any valid command that would be accepted at the
131normal boot prompt. 131normal boot prompt.
132In addition, 132In addition,
133.Dq Ic prompt 133.Dq Ic prompt
134can be used to drop to the normal boot prompt. 134can be used to drop to the normal boot prompt.
135.It Sy timeout 135.It Sy timeout
136If the value is greater than zero, this specifies the time in seconds 136If the value is greater than zero, this specifies the time in seconds
137that the boot loader will wait for the end-user to choose a menu item. 137that the boot loader will wait for the end-user to choose a menu item.
138During the countdown period, they may press Return to choose the default 138During the countdown period, they may press Return to choose the default
139option or press a number key corresponding to a menu option. 139option or press a number key corresponding to a menu option.
140If any other key is pressed, the countdown will stop and the user will be 140If any other key is pressed, the countdown will stop and the user will be
141prompted to choose a menu option with no further time limit. 141prompted to choose a menu option with no further time limit.
142If the timeout value is set to zero, the default option will be booted 142If the timeout value is set to zero, the default option will be booted
143immediately. 143immediately.
144If the timeout value is negative or is not a number, there will be no 144If the timeout value is negative or is not a number, there will be no
145time limit for the user to choose an option. 145time limit for the user to choose an option.
146.El 146.El
147.Sh EXAMPLES 147.Sh EXAMPLES
148Here is an example 148Here is an example
149.Nm 149.Nm
150file: 150file:
151.Bd -literal -offset indent 151.Bd -literal -offset indent
152banner=Welcome to NetBSD 152banner=Welcome to NetBSD
153banner================== 153banner==================
154banner= 154banner=
155banner=Please choose an option from the following menu: 155banner=Please choose an option from the following menu:
156menu=Boot normally:boot 156menu=Boot normally:boot
157menu=Boot single-user:boot -s 157menu=Boot single-user:boot -s
158menu=Boot from second disk:boot hd1a: 158menu=Boot from second disk:boot hd1a:
159menu=Boot with module foo:load /foo.kmod;boot 159menu=Boot with module foo:load /foo.kmod;boot
160menu=Boot with modules foo and bar:load /foo.kmod;load /bar.kmod;boot 160menu=Boot with modules foo and bar:load /foo.kmod;load /bar.kmod;boot
161menu=Boot Xen with 256MB for dom0:load /netbsd-XEN3_DOM0 console=pc;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M 161menu=Boot Xen with 256MB for dom0:load /netbsd-XEN3_DOM0 console=pc;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M
162menu=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 162menu=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
163menu=Boot Xen with dom0 in single-user mode:load /netbsd-XEN3_DOM0 -s;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M 163menu=Boot Xen with dom0 in single-user mode:load /netbsd-XEN3_DOM0 -s;multiboot /usr/pkg/xen3-kernel/xen.gz dom0_mem=256M
164menu=Go to command line (advanced users only):prompt 164menu=Go to command line (advanced users only):prompt
165clear=1 165clear=1
166timeout=-1 166timeout=-1
167default=1 167default=1
168# Always load ramdisk module 168# Always load ramdisk module
169load=/miniroot.kmod 169load=/miniroot.kmod
170.Ed 170.Ed
171.Pp 171.Pp
172N.B. Xen counts serial ports from com1 upwards, but 172N.B. Xen counts serial ports from com1 upwards, but
173.Nx 173.Nx
174counts from com0, so the appropriate device name must be used. 174counts from com0, so the appropriate device name must be used.
175Please see the Xen with serial console example above. 175Please see the Xen with serial console example above.
176.Pp 176.Pp
177This will clear the screen and display: 177This will clear the screen and display:
178.Bd -literal -offset indent 178.Bd -literal -offset indent
179Welcome to NetBSD 179Welcome to NetBSD
180================= 180=================
181 181
182Please choose an option from the following menu: 182Please choose an option from the following menu:
183 183
184 1. Boot normally 184 1. Boot normally
185 2. Boot single-user 185 2. Boot single-user
186 3. Boot from second disk 186 3. Boot from second disk
187 4. Boot with module foo 187 4. Boot with module foo
188 5. Boot with modules foo and bar 188 5. Boot with modules foo and bar
189 6. Boot Xen with 256 MB for dom0 189 6. Boot Xen with 256 MB for dom0
190 7. Boot Xen with 256 MB for dom0 (serial) 190 7. Boot Xen with 256 MB for dom0 (serial)
191 8. Boot Xen with dom0 in single-user mode 191 8. Boot Xen with dom0 in single-user mode
192 9. Go to command line (advanced users only) 192 9. Go to command line (advanced users only)
193 193
194Option [1]: 194Option [1]:
195.Ed 195.Ed
196.Pp 196.Pp
197It will then wait for the user to type 1, 2, 3, 4, 5, 6, 7, 8 or 9 followed by 197It will then wait for the user to type 1, 2, 3, 4, 5, 6, 7, 8 or 9 followed by
198Return. 198Return.
199Pressing Return by itself will run option 1. 199Pressing Return by itself will run option 1.
200There will be no timeout. 200There will be no timeout.
201.Sh SEE ALSO 201.Sh SEE ALSO
202.Xr boot 8 , 202.Xr boot 8 ,
203.Xr boothowto 8 203.Xr boothowto 9
204.Sh HISTORY 204.Sh HISTORY
205The 205The
206.Nm 206.Nm
207file appeared in 207file appeared in
208.Nx 5.0 . 208.Nx 5.0 .
209.Sh AUTHORS 209.Sh AUTHORS
210The 210The
211.Nm 211.Nm
212extensions to 212extensions to
213.Xr boot 8 213.Xr boot 8
214were written by 214were written by
215.An Stephen Borrill 215.An Stephen Borrill
216.Aq sborrill@NetBSD.org . 216.Aq sborrill@NetBSD.org .
217.Sh BUGS 217.Sh BUGS
218Support for 218Support for
219.Nm 219.Nm
220is currently for 220is currently for
221.Nx Ns /i386 221.Nx Ns /i386
222and 222and
223.Nx Ns /amd64 223.Nx Ns /amd64
224only. 224only.
225It is hoped that its use will be extended to other appropriate ports that 225It is hoped that its use will be extended to other appropriate ports that
226use the 226use the
227.Xr boot 8 227.Xr boot 8
228interface. 228interface.