1.\" $NetBSD: boot.8,v 1.2 2004/01/07 12:55:42 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 January 7, 2004 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.El 81.Ss Power fail and crash recovery 82Normally, the system will reboot itself at power-up or after crashes. 83An automatic consistency check of the file systems will be performed, 84and unless this fails, the system will resume multi-user operations. 85.Ss Cobalt Boot Sequence 86The first program to take a control after reboot or at power-on is the 87.Tn Cobalt 88.Tn Firmware . 89The 90.Tn Firmware 91can load a compressed kernel from disk, subject to a few limitations. 92The 93.Tn Firmware 94expects the disk to contain DOS-style partition information with 95the first partition being a boot one which is special in that it 96should reside close to the beginning of the disk and must contain 97an 98.Tn ext2 99file system with a 100.Pa boot 101directory which is treated specially by the 102.Tn Firmware . 103The default sequence is pretty straightforward, the 104.Tn Firmware 105finds the boot partition, mounts the ext2 file system from it and 106tries to load a compressed kernel image from the 107.Pa boot 108directory. 109The name of the kernel image differs from machine to machine and 110this is the reason for having multiple copies of 111.Nx 112kernel installed under different names. 113The following kernel image names are known to be in use by certain 114.Tn Cobalt 115flavors: 116.Bd -unfilled -offset indent 117.Pa /boot/vmlinuz.gz 118.Pa /boot/vmlinux.gz 119.Pa /boot/vmlinux-nfsroot.gz 120.Pa /boot/vmlinux_RAQ.gz 121.Pa /boot/vmlinux_raq-2800.gz 122.Ed 123.Pp 124where 125.Pa /boot 126is the directory on the boot partition. 127.Pp 128The 129.Tn Firmware 130console provides the means to alter the default boot sequence and/or 131to specify boot parameters. 132Pressing 133.Sq Aq space 134right after the 135.Tn Firmware 136printed its greeting brings the 137.Tn Firmware 138console prompt and pressing 139.Sq \&? 140at the prompt prints a help screen with all commands supported by 141the 142.Tn Firmware . 143For example, the 144.Sq bfd 145command can be used to boot a kernel image: 146.Bd -unfilled -offset indent 147Cobalt: bfd /boot/\*[Lt]kernel image\*[Gt] [options] 148.Ed 149.Pp 150where 151.Dq options 152are the kernel options. 153.Ss Bootstrap from disk using the standard Firmware sequence 154The 155.Tn Firmware 156enters the standard boot sequence after reboot or at power-on when 157no front-panel buttons are pressed and the 158.Tn Firmware 159console is not used to change the boot procedure. 160At boot time, the 161.Tn Firmware 162checks the hardware, prints the banner and performs the standard 163.Tn Cobalt 164boot sequence. 165There are a few culprits tightly connected to this boot method. 166First of all, the kernel must be compressed. 167Second, the 168.Tn Firmware 169enforces a hard restriction on the kernel size 170.Po 171it cannot exceed approximately 1000000/2500000 bytes 172compressed/uncompressed 173.Pc 174resulting in a lock-up should this requirement not be fulfilled. 175For 176.Nx , 177another pitfall is that the uncompressed kernel should be copied to 178the root directory to make certain system binaries 179.Po 180such as e.g. netstat 181.Pc 182work, and the kernel images in the 183.Pa boot 184directory should always be in sync with the ones installed in the 185root directory. 186.Ss Bootstrap from disk using the NetBSD boot loader 187The 188.Nx 189boot loader is an attempt to break through the limitations enforced 190by the 191.Tn Firmware 192loader. 193The main idea is to make the 194.Tn Firmware 195load the 196.Nx 197boot loader and let the latter take care of loading the kernel. 198To achieve this goal, multiple copies of the boot loader are 199installed in the 200.Pa boot 201directory on the boot partition, one copy per each kernel image 202name the 203.Tn Cobalt 204.Tn Firmware 205might look for. 206The 207.Nx 208kernel is located in the root directory 209.Po 210usually 211.Pa /dev/wd0a 212.Pc 213like it is on other platforms. 214Once running, the boot loader prints a banner similar to the following: 215.Bd -unfilled -offset indent 216\*[Gt]\*[Gt] NetBSD/cobalt 1.6ZG Bootloader, Revision 0.1 [@0x81000000] 217\*[Gt]\*[Gt] (user@buildhost, builddate) 218\*[Gt]\*[Gt] Memory: 32768 k 219\*[Gt]\*[Gt] Firmware boot string: root=/dev/hda1 ro 220Loading: wd0a:netbsd 2212249104+195856 [81872+73284]=0x27af90 222Starting at 0x80001000 223.Ed 224.Pp 225by default, the boot loader uses 226.Dq Li wd0a:netbsd 227as kernel specification which corresponds to the file 228.Nm netbsd 229on partition 230.Dq a 231of the 232.Nx 233.Tn MBR 234partition of the first hard disk known to the 235.Tn Firmware 236.Po 237which is an 238.Tn IDE 239or similar device - see the 240.Sx BUGS 241section 242.Pc . 243In case this fails, the boot loader will try a few alternative 244kernel image names and if this also fails the loader will repeat 245the whole procedure for all other 246.Nx 247slices 248.Pq if any 249and will load the first kernel image found. 250.Ss Boot loader Options 251It is possible to specify some options to the boot loader by breaking 252into the 253.Tn Firmware 254and using the 255.Dq bfd 256command: 257.Bd -unfilled -offset indent 258Cobalt: bfd /boot/boot.gz [options] 259.Ed 260.Pp 261The boot loader allows the following options: 262.Bl -tag -width 04n -offset 04n 263.It Xo Ic nbsd= 264.Op Va device : Ns 265.Op Va filename 266.Op Fl acdqsv 267.Xc 268The default 269.Va device 270will be set to 271.Va wd0a 272which is the first 273.Nx 274partition on the first drive, as numbered by the 275.Tn Firmware . 276To boot from an alternate disk, the full name of the device should 277be given at the prompt. 278.Va device 279is of the form 280.Va xdNx 281where 282.Va xd 283is the device from which to boot, 284.Va N 285is the unit number, and 286.Va x 287is the partition letter. 288.Pp 289The following list of supported devices may vary from installation to 290installation: 291.Pp 292.Bl -hang -compact 293.It wd 294Hard disks as numbered by the BIOS. This includes ST506, IDE, ESDI, 295RLL disks on a WD100[2367] or lookalike controller(s), and SCSI 296disks on SCSI controllers recognized by the 297.Tn Firmware . 298.El 299.Pp 300The default 301.Va filename 302is 303.Pa netbsd ; 304if the boot loader fails to successfully 305open that image, it then tries 306.Pa netbsd.gz 307(expected to be a kernel image compressed by 308.Xr gzip 1 ) , 309followed by 310.Pa netbsd , 311.Pa netbsd.gz , 312.Pa onetbsd , 313.Pa onetbsd.gz , 314.Pa netbsd.bak , 315.Pa netbsd.bak.gz , 316.Pa netbsd.old , 317.Pa netbsd.old.gz , 318.Pa netbsd.cobalt , 319.Pa netbsd.cobalt.gz , 320.Pa netbsd.elf , 321and finally 322.Pa netbsd.elf.gz . 323Alternate system images can be loaded by just specifying the name 324of the image. 325.Pp 326Options are: 327.Bl -tag -width xxx 328.It Fl a 329Prompt for the root file system device, the system crash dump 330device, and the path to 331.Xr init 8 . 332.It Fl c 333Bring the system up into the device configuration manager. 334From here the device locators can be tuned to the hardware; see 335.Xr userconf 4 . 336.It Fl d 337Bring the system up in debug mode. 338Here it waits for a kernel debugger connect; see 339.Xr ddb 4 . 340.It Fl q 341Boot the system in quiet mode. 342.It Fl s 343Bring the system up in single-user mode. 344.It Fl v 345Boot the system in verbose mode. 346.El 347.El 348.Pp 349It is always a good idea to have a small rescue kernel in the 350.Pa boot 351directory. 352In an emergency case, this will allow you to use the 353.Tn Firmware 354.Sq bfd 355command to boot the rescue image: 356.Bd -unfilled -offset indent 357Cobalt: bfd /boot/netbsd.gz 358.Ed 359.Ss Network bootstrap using the standard Firmware sequence 360The 361.Tn Cobalt 362.Tn Firmware 363allows to boot a kernel over the network, with all the limitations 364of the 365.Tn Firmware 366loader described above. 367The simplest method is to break into the 368.Tn Firmware 369prompt and use 370.Dq bfd 371command to specify where to boot from: 372.Bd -unfilled -offset indent 373Cobalt: bfd /netbsd.gz nfsroot=/home/raq/root 374.Ed 375.Pp 376The 377.Tn Firmware 378is picky about syntax and in general, so if things fail mysteriously, 379try to conform to the conventions described above. 380For netbooting, you need to NFS-export the directory given to 381.Dq nfsroot= , 382and the named kernel 383.Pq Pa netbsd.gz 384needs to be executable and in that directory. 385You will also need to setup 386.Xr rarpd 8 387and 388.Xr dhcpd 8 . 389Once the kernel is loaded with the command line values, the data 390given via DHCP is used to mount the root filesystem. 391Here is a known working DHCP entry: 392.Bd -unfilled -offset indent 393host raq { 394 hardware ethernet 0:10:e0:0:52:62; # raq MAC 395 fixed-address 10.0.0.15; # raq address 396 filename "/netbsd.gz"; # kernel name in root-path 397 option root-path "/home/raq/root"; # absolute dir on nfs server 398 server-name="10.0.0.3"; # IP of nfs server 399} 400.Ed 401.Pp 402Another option is to hold down the left and right cursor buttons 403during power-on which executes the command 404.Bd -unfilled -offset indent 405bfd /boot/vmlinux.gz root=/dev/nfs nfsroot=/nfsroot, 406.Ed 407.Pp 408resulting in a netboot. 409On RaQ 1's, the default kernel name is 410.Pa vmlinux_RAQ.gz 411and on RaQ 2's, it is 412.Pa vmlinux_raq-2800.gz . 413.Sh FILES 414.Bl -tag -width /usr/mdec/bootxx_fstype -compact 415.It Pa /boot/boot.gz 416boot program code loaded by the 417.Tn Firmware 418loader 419.It Pa /boot/netbsd.gz 420.Xr gzip 1 Ns -compressed 421rescue system code 422.It Pa /netbsd 423system code 424.It Pa /netbsd.gz 425.Xr gzip 1 Ns -compressed 426system code 427.El 428.Sh SEE ALSO 429.Xr ddb 4 , 430.Xr userconf 4 , 431.Xr fdisk 8 , 432.Xr halt 8 , 433.Xr reboot 8 , 434.Xr shutdown 8 435.Sh BUGS 436The 437.Nx 438boot loader supports booting off IDE hard drives only. 439This is less a bug of the boot loader code than a shortcoming of 440the 441.Tn Cobalt 442.Tn Firmare 443and shall be considered as such. 444