1.\" $NetBSD: boot.8,v 1.6 2008/11/06 19:40:03 wiz 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 November 6, 2008 36.Dt BOOT 8 cobalt 37.Os 38.Sh NAME 39.Nm boot 40.Nd system bootstrapping procedures 41.Sh DESCRIPTION 42.Tn Cobalt 43Networks' MIPS-based Microservers 44.Po 45now known as 46.Tn Sun 47Server Appliances 48.Pc 49that can run 50.Nx Ns /cobalt 51can use any of the following boot procedures: 52.Pp 53.Bl -bullet 54.It 55bootstrap 56.Nx 57from disk using the standard 58.Tn Cobalt 59.Tn Firmware 60boot sequence 61.It 62bootstrap 63.Nx 64from disk using the 65.Nx 66boot loader 67.It 68network bootstrap 69.Nx 70using the standard 71.Tn Cobalt 72.Tn Firmware 73means from a 74.Tn TCP/IP 75.Tn LAN 76with 77.Tn DHCP 78and 79.Tn NFS . 80.It 81network bootstrap 82.Nx 83using the 84.Nx 85boot loader which can be loaded by the standard Cobalt Firmware 86with DHCP and NFS. 87.El 88.Ss Power fail and crash recovery 89Normally, the system will reboot itself at power-up or after crashes. 90An automatic consistency check of the file systems will be performed, 91and unless this fails, the system will resume multi-user operations. 92.Ss Cobalt Boot Sequence 93The first program to take a control after reboot or at power-on is the 94.Tn Cobalt 95.Tn Firmware . 96The 97.Tn Firmware 98can load a compressed kernel from disk, subject to a few limitations. 99The 100.Tn Firmware 101expects the disk to contain DOS-style partition information with 102the first partition being a boot one which is special in that it 103should reside close to the beginning of the disk and must contain 104an 105.Tn Ext2 106file system with a 107.Pa boot 108directory which is treated specially by the 109.Tn Firmware . 110The default sequence is pretty straightforward, the 111.Tn Firmware 112finds the boot partition, mounts the Ext2 file system from it and 113tries to load a compressed kernel image from the 114.Pa boot 115directory. 116The name of the kernel image differs from machine to machine and 117this is the reason for having multiple copies of 118.Nx 119kernel installed under different names. 120The following kernel image names are known to be in use by certain 121.Tn Cobalt 122flavors: 123.Bd -unfilled -offset indent 124.Pa /boot/vmlinuz.gz 125.Pa /boot/vmlinux.gz 126.Pa /boot/vmlinux-nfsroot.gz 127.Pa /boot/vmlinux_RAQ.gz 128.Pa /boot/vmlinux_raq-2800.gz 129.Ed 130.Pp 131where 132.Pa /boot 133is the directory on the boot partition. 134.Pp 135The 136.Tn Firmware 137console provides the means to alter the default boot sequence and/or 138to specify boot parameters. 139Pressing 140.Sq Aq space 141right after the 142.Tn Firmware 143printed its greeting brings the 144.Tn Firmware 145console prompt and pressing 146.Sq \&? 147at the prompt prints a help screen with all commands supported by 148the 149.Tn Firmware . 150For example, the 151.Sq bfd 152command can be used to boot a kernel image: 153.Bd -unfilled -offset indent 154Cobalt: bfd /boot/\*[Lt]kernel image\*[Gt] [options] 155.Ed 156.Pp 157where 158.Dq options 159are the kernel options. 160.Ss Bootstrap from disk using the standard Firmware sequence 161The 162.Tn Firmware 163enters the standard boot sequence after reboot or at power-on when 164no front-panel buttons are pressed and the 165.Tn Firmware 166console is not used to change the boot procedure. 167At boot time, the 168.Tn Firmware 169checks the hardware, prints the banner and performs the standard 170.Tn Cobalt 171boot sequence. 172There are a few culprits tightly connected to this boot method. 173First of all, the kernel must be compressed. 174Second, the 175.Tn Firmware 176enforces a hard restriction on the kernel size 177.Po 178it cannot exceed approximately 900,000/2,500,000 bytes 179compressed/uncompressed 180.Pc 181resulting in a lock-up should this requirement not be fulfilled. 182For 183.Nx , 184another pitfall is that the uncompressed kernel should be copied to 185the root directory to make certain system binaries 186.Po 187such as e.g. netstat 188.Pc 189work, and the kernel images in the 190.Pa boot 191directory should always be in sync with the ones installed in the 192root directory. 193.Ss Bootstrap from disk using the NetBSD boot loader 194The 195.Nx 196boot loader is an attempt to break through the limitations enforced 197by the 198.Tn Firmware 199loader. 200The main idea is to make the 201.Tn Firmware 202load the 203.Nx 204boot loader and let the latter take care of loading the kernel. 205To achieve this goal, multiple copies of the boot loader are 206installed in the 207.Pa boot 208directory on the boot partition, one copy per each kernel image 209name the 210.Tn Cobalt 211.Tn Firmware 212might look for. 213The 214.Nx 215kernel is located in the root directory 216.Po 217usually 218.Pa /dev/wd0a 219.Pc 220like it is on other platforms. 221Once running, the boot loader prints a banner to the serial console 222similar to the following: 223.Bd -unfilled -offset indent 224\*[Gt]\*[Gt] NetBSD/cobalt 5.0 Bootloader, Revision 0.9 [@0x80f00000] 225\*[Gt]\*[Gt] (user@buildhost, builddate) 226\*[Gt]\*[Gt] Model: Cobalt Qube 2 227\*[Gt]\*[Gt] Memory: 32768 k 228\*[Gt]\*[Gt] PROM boot string: root=/dev/hda1 ro 229Boot [wd0a:netbsd]: 230Loading: wd0a:netbsd 2313763776+312244 [216944+209676]=0x44b97c 232Starting at 0x80001000 233.Ed 234.Pp 235The boot loader also prints a banner to the LCD panels as the following: 236.Bd -unfilled -offset indent 237.Nx Ns /cobalt 238Bootloader 239.Pp 240Loading: 241wd0a:netbsd 242.Ed 243.Ss Boot loader Options 244It is possible to specify some options and boot devices on the boot loader 245prompt: 246.Pp 247.Xo No boot [wd0a:netbsd]: 248.Op Va device : Ns 249.Op Va filename 250.Op Fl acdmqsvxz 251.Xc 252.Pp 253The default 254.Va device 255will be set to the disk that the boot loader was loaded from. 256To boot from an alternate disk or partition, the full name of the device should 257be given at the prompt. 258.Va device 259is of the form 260.Va xdNx 261where 262.Va xd 263is the device from which to boot, 264.Va N 265is the unit number, and 266.Va x 267is the partition letter of the NetBSD 268.Xr disklabel 5 269in the NetBSD partition of the MBR partitions. 270The 271.Nx 272boot loader recognizes FFS (both UFS1 and UFS2) and Linux Ext2fs. 273.Pp 274The following list of supported devices may vary from installation to 275installation: 276.Pp 277.Bl -hang -compact 278.It wd 279IDE hard disks recognized by the 280.Tn Firmware . 281.El 282.Pp 283The default 284.Va filename 285is 286.Pa netbsd ; 287if the boot loader fails to successfully 288open that image, it then tries 289.Pa netbsd.gz 290(expected to be a kernel image compressed by 291.Xr gzip 1 ) , 292followed by 293.Pa netbsd , 294.Pa netbsd.gz , 295.Pa onetbsd , 296.Pa onetbsd.gz , 297.Pa netbsd.bak , 298.Pa netbsd.bak.gz , 299.Pa netbsd.old , 300.Pa netbsd.old.gz , 301.Pa netbsd.cobalt , 302.Pa netbsd.cobalt.gz , 303.Pa netbsd.elf , 304and finally 305.Pa netbsd.elf.gz . 306Alternate system images can be loaded by just specifying the name 307of the image, so it is always a good idea to have a copy of working kernel 308in the 309.Nx 310root partition before trying a new kernel. 311.Pp 312Options are: 313.Bl -tag -width xxx 314.It Fl a 315Prompt for the root file system device, the system crash dump 316device, and the path to 317.Xr init 8 . 318.It Fl c 319Bring the system up into the device configuration manager. 320From here the device locators can be tuned to the hardware; see 321.Xr userconf 4 . 322.It Fl d 323Bring the system up in debug mode. 324Here it waits for a kernel debugger connect; see 325.Xr ddb 4 . 326.It Fl q 327Boot the system in quiet mode. 328.It Fl s 329Bring the system up in single-user mode. 330.It Fl v 331Boot the system in verbose mode. 332.El 333.Pp 334As the older version of the boot loader, it is also possible to specify 335options to the boot loader by breaking into the 336.Tn Firmware 337and using the 338.Dq bfd 339command: 340.Bd -unfilled -offset indent 341Cobalt: bfd /boot/boot.gz [options] 342.Ed 343.Pp 344The boot loader allows the following options: 345.Bl -tag -width 04n -offset 04n 346.It Xo Ic nbsd= 347.Op Va device : Ns 348.Op Va filename 349.Op Fl acdqsv 350.Xc 351.Pp 352The device, filename and options on the bfd prompt are same with the boot 353loader. 354.El 355.Pp 356It is also a good idea to have a small rescue kernel in the 357.Pa boot 358directory in the Ext2 partition for the Firmware boot. 359In an emergency case, this will allow you to use the 360.Tn Firmware 361.Sq bfd 362command to boot the rescue image: 363.Bd -unfilled -offset indent 364Cobalt: bfd /boot/netbsd.gz 365.Ed 366.Ss Network bootstrap using the standard Firmware sequence 367The 368.Tn Cobalt 369.Tn Firmware 370allows to boot a kernel over the network, with all the limitations 371of the 372.Tn Firmware 373loader described above. 374The simplest method is to break into the 375.Tn Firmware 376prompt and use 377.Dq bfd 378command to specify where to boot from: 379.Bd -unfilled -offset indent 380Cobalt: bfd /netbsd.gz nfsroot=/home/raq/root 381.Ed 382.Pp 383The 384.Tn Firmware 385is picky about syntax and in general, so if things fail mysteriously, 386try to conform to the conventions described above. 387For netbooting, you need to NFS-export the directory given to 388.Dq nfsroot= , 389and the named kernel 390.Pq Pa netbsd.gz 391needs to be executable and in that directory. 392You will also need to setup 393.Xr dhcpd 8 . 394Once the kernel is loaded with the command line values, the data 395given via DHCP is used to mount the root file system. 396Here is a known working DHCP entry: 397.Bd -unfilled -offset indent 398host raq { 399 hardware ethernet 0:10:e0:0:52:62; # raq MAC 400 fixed-address 10.0.0.15; # raq address 401 filename "/netbsd.gz"; # kernel name in root-path 402 option root-path "/home/raq/root"; # absolute dir on NFS server 403 server-name="10.0.0.3"; # IP of NFS server 404} 405.Ed 406.Pp 407Another option is to hold down the left and right cursor buttons 408during power-on which executes the command 409.Bd -unfilled -offset indent 410bfd /boot/vmlinux.gz root=/dev/nfs nfsroot=/nfsroot, 411.Ed 412.Pp 413resulting in a netboot. 414On RaQ 1's, the default kernel name is 415.Pa vmlinux_RAQ.gz 416and on RaQ 2's, it is 417.Pa vmlinux_raq-2800.gz . 418.Ss Network bootstrap using the NetBSD boot loader 419The idea here is the same with the bootstrap from disk using the NetBSD 420boot loader. 421Make the firmware load the NetBSD boot loader via network and 422let the latter take care of loading the kernel even via network. 423A simple method to load the NetBSD boot loader is to use the 424.Dq bfd 425command as well as booting the NetBSD kernel via network as described above: 426.Bd -unfilled -offset indent 427Cobalt: bfd /boot/boot.gz nfsroot=/home/raq/root 428.Ed 429.Pp 430Note the boot loader binary needs to be 431.Xr gzip 1 Ns -compressed . 432Once the boot loader is successfully loaded it prints a banner as well as 433booting from disk: 434.Bd -unfilled -offset indent 435\*[Gt]\*[Gt] NetBSD/cobalt 5.0 Bootloader, Revision 0.9 [@0x80f00000] 436\*[Gt]\*[Gt] (user@buildhost, builddate) 437\*[Gt]\*[Gt] Model: Cobalt Qube 2 438\*[Gt]\*[Gt] Memory: 32768 k 439\*[Gt]\*[Gt] PROM boot string: root=/dev/nfs nfsroot=/nfsroot nfsaddrs=bootp 440Boot [nfs:netbsd]: 441Loading: nfs:netbsd 4423763776+312244 [216944+209676]=0x44b97c 443Starting at 0x80001000 444.Ed 445.Pp 446The boot loader load the NetBSD kernel via NFS which should be specified 447by the DHCP configuration on the server. 448Note the nfsroot option specified on the 449.Dq bfd 450prompt will be ignored by the 451.Nx 452boot loader so it's recommended to use the same directory on the 453.Dq bfd 454prompt and in the DHCP configuration. 455.Sh FILES 456.Bl -tag -width /usr/mdec/bootxx_fstype -compact 457.It Pa /boot/boot.gz 458boot program code loaded by the 459.Tn Firmware 460loader 461.It Pa /boot/netbsd.gz 462.Xr gzip 1 Ns -compressed 463rescue system code 464.It Pa /netbsd 465system code 466.It Pa /netbsd.gz 467.Xr gzip 1 Ns -compressed 468system code 469.It Pa /usr/mdec/boot 470master copy of the boot program (to be compressed and copied to /boot/boot.gz) 471.El 472.Sh SEE ALSO 473.Xr ddb 4 , 474.Xr userconf 4 , 475.Xr dhcpd.conf 5 , 476.Xr dhcpd 8 , 477.Xr fdisk 8 , 478.Xr halt 8 , 479.Xr reboot 8 , 480.Xr shutdown 8 , 481.Xr printf 9 482.Pp 483.Lk http://www.NetBSD.org/docs/network/netboot/ 484