| blob | 1da348daa731f061a57ede0a780e25033e0f6973 |
1 .\" $NetBSD: boot.8,v 1.58 2011/05/31 03:43:47 uebayasi Exp $
2 .\"
3 .\" Copyright (c) 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software written and contributed
7 .\" to Berkeley by William Jolitz.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\"
33 .\" @(#)boot_i386.8 8.2 (Berkeley) 4/19/94
34 .\"
35 .Dd May 26, 2011
36 .Dt BOOT 8 i386
37 .Os
38 .Sh NAME
39 .Nm boot
40 .Nd
41 system bootstrapping procedures
42 .Sh DESCRIPTION
43 .Tn IA-32
44 computers
45 .Po
46 the
47 .Tn IBM PC
48 and its clones
49 .Pc
50 that can run
51 .Nx Ns /i386
52 can use any of the following boot procedures, depending on what the hardware and
53 .Tn BIOS
54 support:
55 .Pp
56 .Bl -tag -width "pxeboot(8)"
57 .It boot
58 bootstrap
59 .Nx
60 from the system
61 .Tn BIOS
62 .It Xr dosboot 8
63 bootstrap
64 .Nx
65 from
66 .Tn MS-DOS
67 .It Xr w95boot 8
68 bootstrap
69 .Nx
70 from
71 .Tn Windows 95
72 .It Xr pxeboot 8
73 network bootstrap
74 .Nx
75 from a
76 .Tn TCP/IP
77 .Tn LAN
78 with
79 .Tn DHCP ,
80 .Tn TFTP ,
81 and
82 .Tn NFS .
83 .El
84 .Ss Power fail and crash recovery
85 Normally, the system will reboot itself at power-up or after crashes.
86 An automatic consistency check of the file systems will be performed,
87 and unless this fails, the system will resume multi-user operations.
88 .Ss Cold starts
89 The 386
90 .Tn "PC AT"
91 clones attempt to boot the floppy disk drive A (otherwise known as drive
92 0) first, and failing that, attempt to boot the hard disk C (otherwise
93 known as hard disk controller 1, drive 0).
94 The
95 .Nx
96 bootblocks are loaded and started either by the
97 .Tn BIOS ,
98 or by a boot selector program (such as OS-BS, BOOTEASY, the OS/2 Boot Menu or
99 .Nx Ns 's
100 .No boot-selecting
101 master boot record - see
102 .Xr mbr 8 ) .
103 .Ss Normal Operation
104 Once running, a banner similar to the following will appear:
105 .Bd -unfilled -offset indent
106 \*[Gt]\*[Gt] NetBSD BIOS Boot, revision 3.0
107 \*[Gt]\*[Gt] (user@buildhost, builddate)
108 \*[Gt]\*[Gt] Memory: 637/15360 k
109 Press return to boot now, any other key for boot menu
110 booting hd0a:netbsd - starting in 5
111 .Ed
112 .Pp
113 After a countdown, the system image listed will be loaded.
114 In the example above, it will be
115 .Dq Li hd0a:netbsd
116 which is the file
117 .Nm netbsd
118 on partition
119 .Dq a
120 of the
121 .Nx
122 .Tn MBR
123 partition of the first hard disk known to the
124 .Tn BIOS
125 .Po
126 which is an
127 .Tn IDE
128 or similar device - see the
129 .Sx BUGS
130 section
131 .Pc .
132 .Pp
133 Pressing a key within the time limit, or before the boot program starts, will
134 enter interactive mode.
135 When using a short or 0 timeout, it is often useful to interrupt the boot
136 by holding down a shift key, as some BIOSes and BIOS extensions will drain the
137 keystroke buffer at various points during POST.
138 .Pp
139 If present, the file
140 .Pa /boot.cfg
141 will be used to configure the behaviour of the boot loader including
142 setting the timeout, choosing a console device, altering the banner
143 text and displaying a menu allowing boot commands to be easily chosen.
144 See
145 .Xr boot.cfg 5 .
146 .Pp
147 The
148 .Nx Ns /i386
149 boot loader can boot a kernel using either the native
150 .Nx
151 boot protocol, or the
152 .Dq multiboot
153 protocol (which is compatible with some other operating systems).
154 In the native
155 .Nx
156 boot protocol, options are passed from the boot loader
157 to the kernel via flag bits in the
158 .Va boothowto
159 variable (see
160 .Xr boothowto 9 ) .
161 In the multiboot protocol, options are passed from the boot loader
162 to the kernel as strings.
163 .Ss Diagnostic Output
164 If the first stage boot fails to load the boot, it will print a terse
165 message indicating the reason for the failure.
166 The possible error messages and their cause are listed in
167 .Xr mbr 8 .
168 .Pp
169 If the first stage boot succeeds, the banner will be shown and the
170 error messages should be self-explanatory.
171 .Ss Interactive mode
172 In interactive mode, the boot loader will present a prompt, allowing
173 input of these commands:
174 .\" NOTE: much of this text is duplicated in the MI boot.8.
175 .\" Some of it is
176 .\" also duplicated in the i386-specific dosboot.8 and pxeboot.8;
177 .\" please try to keep all relevant files synchronized.
178 .Bl -tag -width 04n -offset 04n
179 .It Ic boot Oo Va device : Ns Oc Oo Va filename Oc Oo Fl 1234abcdmqsvxz Oc
180 The default
181 .Va device
182 will be set to the disk that the boot loader was
183 loaded from.
184 To boot from an alternate disk, the full name of the device should
185 be given at the prompt.
186 .Va device
187 is of the form
188 .Xo Va xd
189 .Op Va N Ns Op Va x
190 .Xc
191 where
192 .Va xd
193 is the device from which to boot,
194 .Va N
195 is the unit number, and
196 .Va x
197 is the partition letter.
198 .Pp
199 The following list of supported devices may vary from installation to
200 installation:
201 .Pp
202 .Bl -hang -compact
203 .It hd
204 Hard disks as numbered by the BIOS.
205 This includes ST506, IDE, ESDI, RLL disks on a WD100[2367] or
206 lookalike controller(s), and SCSI disks
207 on SCSI controllers recognized by the BIOS.
208 .It fd
209 Floppy drives as numbered by the BIOS.
210 .El
211 .Pp
212 The default
213 .Va filename
214 is
215 .Pa netbsd ;
216 if the boot loader fails to successfully
217 open that image, it then tries
218 .Pa netbsd.gz
219 (expected to be a kernel image compressed by gzip), followed by
220 .Pa netbsd.old ,
221 .Pa netbsd.old.gz ,
222 .Pa onetbsd ,
223 and finally
224 .Pa onetbsd.gz .
225 Alternate system images can be loaded by just specifying the name of the image.
226 .Pp
227 Options are:
228 .Bl -tag -width xxx
229 .It Fl 1
230 Sets the machine-dependent flag
231 .Sy RB_MD1
232 in
233 .Va boothowto .
234 In
235 .Nx Ns /i386 ,
236 this disables multiprocessor boot;
237 the kernel will boot in uniprocessor mode.
238 .It Fl 2
239 Sets the machine-dependent flag
240 .Sy RB_MD2
241 in
242 .Va boothowto .
243 In
244 .Nx Ns /i386 ,
245 this disables ACPI.
246 .It Fl 3
247 Sets the machine-dependent flag
248 .Sy RB_MD3
249 in
250 .Va boothowto .
251 In
252 .Nx Ns /i386 ,
253 this has no effect.
254 .It Fl 4
255 Sets the machine-dependent flag
256 .Sy RB_MD4
257 in
258 .Va boothowto .
259 In
260 .Nx Ns /i386 ,
261 this has no effect.
262 .It Fl a
263 Sets the
264 .Sy RB_ASKNAME
265 flag in
266 .Va boothowto .
267 This causes the kernel to prompt for the root file system device,
268 the system crash dump device, and the path to
269 .Xr init 8 .
270 .It Fl b
271 Sets the
272 .Sy RB_HALT
273 flag in
274 .Va boothowto .
275 This causes subsequent reboot attempts to halt instead of rebooting.
276 .It Fl c
277 Sets the
278 .Sy RB_USERCONF
279 flag in
280 .Va boothowto .
281 This causes the kernel to enter the
282 .Xr userconf 4
283 device configuration manager as soon as possible during the boot.
284 .Xr userconf 4
285 allows devices to be enabled or disabled, and allows device locators
286 (such as hardware addresses or bus numbers)
287 to be modified before the kernel attempts to attach the devices.
288 .It Fl d
289 Sets the
290 .Sy RB_KDB
291 flag in
292 .Va boothowto .
293 Requests the kernel to enter debug mode, in which it
294 waits for a connection from a kernel debugger; see
295 .Xr ddb 4 .
296 .It Fl m
297 Sets the
298 .Sy RB_MINIROOT
299 flag in
300 .Va boothowto .
301 Informs the kernel that a mini-root file system is present in memory.
302 .It Fl q
303 Sets the
304 .Sy AB_QUIET
305 flag in
306 .Va boothowto .
307 Boot the system in quiet mode.
308 .It Fl s
309 Sets the
310 .Sy RB_SINGLE
311 flag in
312 .Va boothowto .
313 Boot the system in single-user mode.
314 .It Fl v
315 Sets the
316 .Sy AB_VERBOSE
317 flag in
318 .Va boothowto .
319 Boot the system in verbose mode.
320 .It Fl x
321 Sets the
322 .Sy AB_DEBUG
323 flag in
324 .Va boothowto .
325 Boot the system with debug messages enabled.
326 .It Fl z
327 Sets the
328 .Sy AB_SILENT
329 flag in
330 .Va boothowto .
331 Boot the system in silent mode.
332 .El
333 .It Ic consdev Va dev
334 Immediately switch the console to the specified device
335 .Va dev
336 and reprint the banner.
337 .Va dev
338 must be one of
339 .\" .Bl -item -width com[0123]kbd -offset indent -compact
340 .Ar pc , com0 , com1 , com2 ,
341 .Ar com3 , com0kbd , com1kbd , com2kbd ,
342 .Ar com3kbd ,
343 or
344 .Ar auto .
345 See
346 .Sx Console Selection Policy
347 in
348 .Xr boot_console 8 .
349 .It Ic dev Op Va device
350 Set the default drive and partition for subsequent filesystem
351 operations.
352 Without an argument, print the current setting.
353 .Va device
354 is of the form specified in
355 .Cm boot .
356 .It Ic help
357 Print an overview about commands and arguments.
358 .It Ic load Va module Op Ar arguments
359 Load the specified kernel
360 .Va module ,
361 and pass it the specified
362 .Ar arguments .
363 If the module name is not an absolute path,
364 .Pa /stand/ Xo Ns
365 .Aq Sy arch Ns
366 .Pa / Ns
367 .Aq Sy osversion Ns
368 .Pa /modules/ Ns
369 .Aq Sy module Ns
370 .Pa / Ns
371 .Aq Sy module Ns
372 .Pa .kmod
373 .Xc
374 is used.
375 Possible used of the
376 .Ic load
377 command include loading a memory disk image before booting a kernel,
378 or loading a
379 .Tn Xen
380 DOM0 kernel before booting the
381 .Tn Xen
382 hypervisor.
383 See
384 .Xr boot.cfg 5
385 for examples.
386 .Pp
387 In addition to the
388 .Cm boot
389 options specified above, the DOM0 kernel accepts
390 .Po Ar arguments
391 being separated with spaces
392 .Pc :
393 .Bl -tag -width xxx
394 .It Ic bootdev Ns = Ns Ar dev Po or Ic root Ns = Ns Ar dev Pc
395 Override the default boot device.
396 .Ar dev
397 can be a unit name
398 .Po Dq wd0
399 .Pc ,
400 or an interface name
401 .Po Dq bge0 ,
402 .Dq wm0 ,
403 .Ns ...
404 .Pc ,
405 for cases where the root file system has to be loaded
406 from network (see the
407 .Sx BUGS
408 section in
409 .Xr pxeboot 8 ) .
410 .It Ic console Ns = Ns Ar dev
411 Console used by DOM0 kernel during boot.
412 .Ar dev
413 accepts the same values as the ones given for the
414 .Cm consdev
415 command.
416 See
417 .Sx Console Selection Policy
418 in
419 .Xr boot_console 8 .
420 .It Xo Ic ip Ns = Ns
421 .Ar my_ip Ns : Ns Ar serv_ip Ns : Ns Ar gw_ip Ns : Ns
422 .Ar mask Ns : Ns Ar host Ns : Ns Ar iface
423 .Xc
424 Specify various parameters for a network boot (IPs are in
425 dot notation),
426 each one separated by a colon:
427 .Bl -tag -width xxxxxxx
428 .It Va my_ip
429 address of the host
430 .It Va serv_ip
431 address of the NFS server
432 .It Va gw_ip
433 address of the gateway
434 .It Va mask
435 network mask
436 .It Va host
437 address of the host
438 .It Va iface
439 interface
440 .Po e.g. Dq xennet0
441 or
442 .Dq eth0
443 .Pc
444 .El
445 .It Ic nfsroot Ns = Ns Ar address Ns : Ns Ar rootpath
446 Boot the system with root on NFS.
447 .Ar address
448 is the address of the NFS server, and
449 .Ar rootpath
450 is the remote mount point for the root file system.
451 .It Ic pciback.hide Ns = Ns Ar pcidevs
452 Pass a list of PCI IDs for use with the PCI backend driver,
453 .Xr pciback 4 .
454 .Ar pcidevs
455 is formed of multiple IDs (in bus:device.function notation),
456 each ID being surrounded with brackets.
457 PCI domain IDs are currently ignored.
458 See
459 .Xr pciback 4 .
460 .El
461 .It Ic load_mods Va mods_path_pattern
462 Load modules specified by pattern like /some_path/mod*.
463 .It Ic ls Op Pa path
464 Print a directory listing of
465 .Pa path ,
466 containing inode number, filename, and file type.
467 .Pa path
468 can contain a device specification.
469 .It Ic modules Bro Ar on | off | enabled | disabled Brc
470 The values
471 .Ar enabled , on
472 will enable module loading for
473 .Cm boot
474 and
475 .Cm multiboot ,
476 whereas
477 .Ar disabled , off
478 will turn off the feature.
479 .It Ic multiboot Va kernel Op Ar arguments
480 Boot the specified
481 .Va kernel ,
482 using the
483 .Dq multiboot
484 protocol instead of the native
485 .Nx
486 boot protocol.
487 The
488 .Va kernel
489 is specified in the same way as with the
490 .Ic boot
491 command.
492 .Pp
493 The multiboot protocol may be used in the following cases:
494 .Bl -tag -width indent
495 .It Nx Ns / Ns Xen No kernels
496 The
497 .Tn Xen
498 DOM0 kernel must be loaded as a module using the
499 .Ic load
500 command, and the
501 .Tn Xen
502 hypervisor must be booted using the
503 .Ic multiboot
504 command.
505 Options for the DOM0 kernel (such as
506 .Dq -s
507 for single user mode) must be passed as options to the
508 .Ic load
509 command.
510 Options for the hypervisor (such as
511 .Dq dom0_mem=256M
512 to reserve 256 MB of memory for DOM0)
513 must be passed as options to the
514 .Ic multiboot
515 command.
516 See
517 .Xr boot.cfg 5
518 for examples on how to boot
519 .Nx Ns / Ns Xen.
520 .It Nx No multiboot kernels
521 A
522 .Nx
523 kernel that was built with
524 .Cd options MULTIBOOT
525 (see
526 .Xr multiboot 8 )
527 may be booted with either the
528 .Ic boot
529 or
530 .Ic multiboot
531 command, passing the same
532 .Ar arguments
533 in either case.
534 .It Non- Ns Nx No kernels
535 A kernel for a
536 .No non- Ns Nx
537 operating system that expects to be booted using the
538 multiboot protocol (such as by the GNU
539 .Dq GRUB
540 boot loader)
541 may be booted using the
542 .Ic multiboot
543 command.
544 See the foreign operating system's documentation for the available
545 .Ar arguments .
546 .El
547 .It Ic quit
548 Reboot the system.
549 .It Ic userconf Va command
550 Pass the
551 .Va command
552 to
553 .Xr userconf 4
554 at boot time .
555 These commands are processed before the interactive
556 .Xr userconf 4
557 shell is executed, if requested .
558 .It Ic vesa Bro Va modenum | Ar on | off | enabled | disabled | list Brc
559 Initialise the video card to the specified resolution and bit depth.
560 The
561 .Va modenum
562 should be in the form of
563 .Ar 0x100 , 800x600 , 800x600x32 .
564 The values
565 .Ar enabled , on
566 put the display into the default mode, and
567 .Ar disabled , off
568 returns the display into standard vga mode.
569 The value
570 .Ar list
571 lists all supported modes.
572 .El
573 .Pp
574 In an emergency, the bootstrap methods described in the
575 .Nx
576 installation notes for the i386 architecture
577 can be used to boot from floppy or other media,
578 or over the network.
579 .Sh FILES
580 .Bl -tag -width /usr/mdec/bootxx_fstype -compact
581 .It Pa /boot
582 boot program code loaded by the primary bootstrap
583 .It Pa /boot.cfg
584 optional configuration file
585 .It Pa /netbsd
586 system code
587 .It Pa /netbsd.gz
588 gzip-compressed system code
589 .It Pa /usr/mdec/boot
590 master copy of the boot program (copy to /boot)
591 .It Pa /usr/mdec/bootxx_fstype
592 primary bootstrap for filesystem type fstype, copied to the start of
593 the
594 .Nx
595 partition by
596 .Xr installboot 8 .
597 .El
598 .Sh SEE ALSO
599 .Xr ddb 4 ,
600 .Xr pciback 4 ,
601 .Xr userconf 4 ,
602 .Xr boot.cfg 5 ,
603 .Xr boot_console 8 ,
604 .Xr dosboot 8 ,
605 .Xr halt 8 ,
606 .Xr installboot 8 ,
607 .Xr mbr 8 ,
608 .Xr multiboot 8 ,
609 .Xr pxeboot 8 ,
610 .Xr reboot 8 ,
611 .Xr shutdown 8 ,
612 .Xr w95boot 8 ,
613 .Xr boothowto 9
614 .Sh BUGS
615 The kernel file name must be specified before, not after, the boot options.
616 Any
617 .Ar filename
618 specified after the boot options, e.g.:
619 .Pp
620 .Bd -unfilled -offset indent -compact
621 .Cm boot -d netbsd.test
622 .Ed
623 .Pp
624 is ignored, and the default kernel is booted.
625 .Pp
626 Hard disks are always accessed by
627 .Tn BIOS
628 functions.
629 Unit numbers are
630 .Tn BIOS
631 device numbers which might differ from numbering in the
632 .Nx
633 kernel or physical parameters
634 .Po
635 e.g.,
636 .Tn SCSI
637 slave numbers
638 .Pc .
639 There isn't any distinction between
640 .Dq sd
641 and
642 .Dq wd
643 devices at the bootloader level.
644 This is less a bug of the bootloader code than
645 a shortcoming of the PC architecture.
646 The default disk device's name printed in the starting message
647 is derived from the
648 .Dq type
649 field of the
650 .Nx
651 disklabel (if it is a hard disk).