1.\" $NetBSD: installboot.8,v 1.41 2004/03/13 23:43:45 wiz Exp $ 2.\" 3.\" Copyright (c) 2002-2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn of Wasabi Systems. 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. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 14, 2004 38.Dt INSTALLBOOT 8 39.Os 40.Sh NAME 41.Nm installboot 42.Nd install disk bootstrap software 43. 44.Sh SYNOPSIS 45.Nm 46.Op Fl nv 47.Bk -words 48.Op Fl m Ar machine 49.Ek 50.Bk -words 51.Op Fl o Ar options 52.Ek 53.Bk -words 54.Op Fl t Ar fstype 55.Ek 56.Bk -words 57.Op Fl b Ar s1bno 58.Ek 59.Bk -words 60.Op Fl B Ar s2bno 61.Ek 62.Ar filesystem 63.Ar primary 64.Op Ar secondary 65.Nm 66.Fl c 67.Op Fl nv 68.Bk -words 69.Op Fl m Ar machine 70.Ek 71.Bk -words 72.Op Fl o Ar options 73.Ek 74.Bk -words 75.Op Fl t Ar fstype 76.Ek 77.Ar filesystem 78. 79.Sh DESCRIPTION 80The 81.Nm 82utility installs and removes 83.Nx 84disk bootstrap software into a file system. 85.Nm 86can install 87.Ar primary 88into 89.Ar filesystem , 90or disable an existing bootstrap in 91.Ar filesystem . 92.Pp 93Generally, 94.Nx 95disk bootstrap software consists of two parts: a 96.Dq primary 97bootstrap program usually written into the disklabel area of the 98file system by 99.Nm , 100and a 101.Dq secondary 102bootstrap program that usually resides as an ordinary file in the file system. 103.Pp 104When booting, the primary bootstrap program is loaded and invoked by 105the machine's PROM or BIOS. 106After receiving control of the system it loads and runs the secondary 107bootstrap program, which in turn loads and runs the kernel. 108The secondary bootstrap may allow control over various boot parameters 109passed to the kernel. 110.Pp 111Perform the following steps to make a file system bootable: 112.Bl -enum 113.It 114Copy the secondary bootstrap (usually 115.Pa /usr/mdec/boot. Ns Sy MACHINE 116or 117.Pa /usr/mdec/boot ) 118to the root directory of the target file system. 119.Pp 120. 121.It 122Use 123.Nm 124to install the primary bootstrap program 125(usually 126.Pa /usr/mdec/bootxx_ Ns Sy FSTYPE ) 127into 128.Ar filesystem . 129.Pp 130The following platforms do not require this step if the primary bootstrap 131already exists and the secondary bootstrap file is just being updated: 132.Sy alpha , 133.Sy amiga , 134.Sy i386 , 135.Sy pmax , 136.Sy sparc64 , 137and 138.Sy vax . 139.Pp 140The following platform does not require the first step since a 141single bootstrap file is used. 142The single bootstrap is installed like the primary bootstrap on 143other platforms: 144.Sy next68k . 145.Pp 146.El 147.Pp 148The options and arguments recognized by 149.Nm 150are as follows: 151. 152.Bl -tag -width "optionsxxx" 153. 154.It Fl b Ar s1bno 155Install 156.Ar primary 157at block number 158.Ar s1bno 159instead of the default location for the machine and file system type. 160.Sy [ alpha , 161.Sy pmax , 162.Sy vax ] 163. 164.It Fl B Ar s2bno 165When hard-coding the blocks of 166.Ar secondary 167into 168.Ar primary , 169start from block 170.Ar s2bno 171instead of trying to determine the block numbers occupied by 172.Ar secondary 173by examining 174.Ar filesystem . 175If this option is supplied, 176.Ar secondary 177should refer to an actual secondary bootstrap (rather than the 178file name of the one present in 179.Ar filesystem ) 180so that its size can be determined. 181. 182.It Fl c 183Clear (remove) any existing bootstrap instead of installing one. 184. 185.It Fl m Ar machine 186Use 187.Ar machine 188as the target machine type. 189The default machine is determined from 190.Xr uname 3 191and then 192.Ev MACHINE . 193The following machines are currently supported by 194.Nm : 195.Bd -ragged -offset indent 196.Sy alpha , 197.Sy amd64 , 198.Sy amiga , 199.Sy hp300 , 200.Sy i386 , 201.Sy macppc , 202.Sy news68k , 203.Sy newsmips , 204.Sy next68k , 205.Sy pmax , 206.Sy sparc , 207.Sy sparc64 , 208.Sy sun2 , 209.Sy sun3 , 210.Sy vax , 211.Sy x68k 212.Ed 213. 214. 215.It Fl n 216Do not write to 217.Ar filesystem . 218. 219.It Fl o Ar options 220Machine specific 221.Nm 222options, comma separated. 223.Pp 224Supported options are (with the machines for they are valid in brackets): 225. 226.Bl -tag -offset indent -width alphasum 227. 228.It Sy alphasum 229.Sy [ alpha ] 230Recalculate and restore the Alpha checksum. 231This is the default for 232.Nx Ns Tn /alpha . 233. 234.It Sy append 235.Sy [ alpha , 236.Sy pmax , 237.Sy vax ] 238Append 239.Ar primary 240to the end of 241.Ar filesystem , 242which must be a regular file in this case. 243. 244.It Sy command=\*[Lt]boot command\*[Gt] 245.Sy [ amiga ] 246Modify the default boot command line. 247. 248.It Sy console=\*[Lt]console name\*[Gt] 249.Sy [ i386 ] 250Set the console device, \*[Lt]console name\*[Gt] must be one of: 251pc, com0, com1, com2, com3, com0kbd, com1kbd, com2kbd or com3kbd. 252. 253.It Sy keymap=\*[Lt]keymap\*[Gt] 254.Sy [ i386 ] 255Set a boot time keyboard translation map. 256Each character in \*[Lt]keymap\*[Gt] will be replaced by the one following it. 257For example, an argument of 258.Dq zyz 259would swap the lowercase letters 260.Sq y 261and 262.Sq z . 263. 264.It Sy password=\*[Lt]password\*[Gt] 265.Sy [ i386 ] 266Set the password which must be entered before the boot menu can be accessed. 267. 268.It Sy resetvideo 269.Sy [ i386 ] 270Reset the video before booting. 271. 272.It Sy speed=\*[Lt]baud rate\*[Gt] 273.Sy [ i386 ] 274Set the baud rate for the serial console. 275. 276.It Sy sunsum 277.Sy [ alpha , 278.Sy pmax , 279.Sy vax ] 280Recalculate and restore the Sun and 281.Nx Ns Tn /sparc 282compatible checksum. 283.Em Note : 284The existing 285.Nx Ns Tn /sparc 286disklabel should use no more than 4 partitions. 287. 288.It Sy timeout=\*[Lt]seconds\*[Gt] 289.Sy [ i386 ] 290Set the timeout before the automatic boot begins to the given number of seconds. 291.El 292. 293.It Fl t Ar fstype 294Use 295.Ar fstype 296as the type of 297.Ar filesystem . 298The default operation is to attempt to auto-detect this setting. 299The following file system types are currently supported by 300.Nm : 301. 302.Bl -tag -offset indent -width ffs 303. 304.It Sy ffs 305.Bx 306Fast File System. 307. 308.It Sy raw 309.Sq Raw 310image. 311Note: if a platform needs to hard-code the block offset of the secondary 312bootstrap, it cannot be searched for on this file system type, and must 313be provided with 314.Fl B Ar s2bno . 315.El 316. 317.It Fl v 318Verbose operation. 319. 320.It Ar filesystem 321The path name of the device or file system image that 322.Nm 323is to operate on. 324It is not necessary for 325.Ar filesystem 326to be a currently mounted file system. 327. 328.It Ar primary 329The path name of the 330.Dq primary 331boot block to install. 332. 333.It Ar secondary 334The path name of the 335.Dq secondary 336boot block, 337relative to the top of 338.Ar filesystem . 339Most systems require 340.Ar secondary 341to be in the 342.Dq root 343directory of the file system, so the leading 344.Dq Pa / 345is not necessary on 346.Ar secondary . 347.Pp 348Only certain combinations of 349platform 350.Pq Fl m Ar machine 351and file system type 352.Pq Fl t Ar fstype 353require that the name of the secondary bootstrap is 354supplied as 355.Ar secondary , 356so that information such as the disk block numbers occupied 357by the secondary bootstrap can be stored in the primary bootstrap. 358These are: 359.Bl -column "Platform" "File systems" -offset indent 360.It Sy "Platform" Ta Sy "File systems" 361.It macppc Ta ffs, raw 362.It news68k Ta ffs, raw 363.It newsmips Ta ffs, raw 364.It sparc Ta ffs, raw 365.It sun2 Ta ffs, raw 366.It sun3 Ta ffs, raw 367.El 368.El 369.Pp 370.Nm 371exits 0 on success, and \*[Gt]0 if an error occurs. 372. 373.Sh ENVIRONMENT 374.Nm 375uses the following environment variables: 376. 377.Bl -tag -width "MACHINE" 378. 379.It Ev MACHINE 380Default value for 381.Ar machine , 382overriding the result from 383.Xr uname 3 . 384. 385.El 386. 387.Sh FILES 388Most 389.Nx 390ports will contain variations of the following files: 391.Pp 392.Bl -tag -width /usr/mdec/bootxx_ustarfs 393. 394.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE 395Primary bootstrap for file system type 396.Sy FSTYPE . 397Installed into the bootstrap area of the file system by 398.Nm . 399. 400.It Pa /usr/mdec/bootxx_ffsv1 401Primary bootstrap for 402.Sy FFSv1 403file systems 404(the "traditional" 405.Nx 406file system). 407. 408.It Pa /usr/mdec/bootxx_ffsv2 409Primary bootstrap for 410.Sy FFSv2 411file systems. 412. 413.It Pa /usr/mdec/bootxx_lfsv1 414Primary bootstrap for 415.Sy LFSv1 416file systems. 417. 418.It Pa /usr/mdec/bootxx_lfsv2 419Primary bootstrap for 420.Sy LFSv2 421file systems 422(the default LFS version). 423. 424.It Pa /usr/mdec/bootxx_msdos 425Primary bootstrap for 426.Tn MS-DOS 427.Sy FAT 428file systems. 429. 430.It Pa /usr/mdec/bootxx_ustarfs 431Primary bootstrap for 432.Sy TARFS 433boot images. 434This is used by various install media. 435. 436.It Pa /usr/mdec/boot. Ns Sy MACHINE 437Secondary bootstrap for machine type 438.Sy MACHINE . 439This should be installed into the file system before 440.Nm 441is run. 442. 443.It Pa /usr/mdec/boot 444Synonym for 445.Pa /usr/mdec/boot. Ns Sy MACHINE 446. 447.It Pa /boot. Ns Sy MACHINE 448Installed copy of secondary bootstrap for machine type 449.Sy MACHINE . 450. 451.It Pa /boot 452Installed copy of secondary bootstrap. 453Searched for by the primary bootstrap if 454.Pa /boot. Ns Sy MACHINE 455is not found. 456. 457.El 458. 459.Ss NetBSD/next68k files 460. 461.Bl -tag -width /usr/mdec/bootxx_ustarfs 462. 463.It Pa /usr/mdec/boot 464.Nx Ns Tn /next68k 465bootstrap. 466. 467.El 468. 469.Ss NetBSD/sparc64 files 470. 471.Bl -tag -width /usr/mdec/bootxx_ustarfs 472. 473.It Pa /usr/mdec/bootblk 474.Nx Ns Tn /sparc64 475primary bootstrap. 476. 477.It Pa /usr/mdec/ofwboot 478.Nx Ns Tn /sparc64 479secondary bootstrap. 480. 481.It Pa /ofwboot 482Installed copy of 483.Nx Ns Tn /sparc64 484secondary bootstrap. 485. 486.El 487. 488.Sh EXAMPLES 489. 490.Ss common 491Verbosely install the Berkeley Fast File System primary bootstrap on to disk 492.Sq sd0 : 493.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs 494.Pp 495Remove the primary bootstrap from disk 496.Sq sd1 : 497.Dl Ic installboot -c /dev/rsd1c 498. 499.Ss NetBSD/amiga 500Modify the command line to change the default from "netbsd -ASn2" to 501"netbsd -S": 502.Dl Ic installboot -m amiga -o command="netbsd -S" /dev/rsd0a /usr/mdec/bootxx_ffs 503. 504.Ss NetBSD/i386 505Install new boot blocks on an existing mounted root file system on 506.Sq wd0 , 507setting the timeout to five seconds, after copying a new secondary 508bootstrap: 509.Dl Ic cp /usr/mdec/boot /boot 510.Dl Ic installboot -v -o timeout=5 /dev/rwd0a /usr/mdec/bootxx_ffsv1 511. 512.Pp 513Create a bootable floppy disk with an FFSv1 514file system for a small custom kernel (note: bigger kernels needing 515multiple disks are handled with the ustarfs file system): 516.Dl Ic newfs -s 1440k /dev/rfd0a 517.Bd -ragged -offset indent-two -compact 518.Em Note: 519Ignore the warnings that 520.Xr newfs 8 521displays; it can not write a disklabel, 522which is not a problem for a floppy disk. 523.Ed 524.Dl Ic mount /dev/fd0a /mnt 525.Dl Ic cp /usr/mdec/boot /mnt/boot 526.Dl Ic gzip -9 \*[Lt] sys/arch/i386/compile/mykernel/netbsd \*[Gt] /mnt/netbsd.gz 527.Dl Ic umount /mnt 528.Dl Ic installboot -v /dev/rfd0a /usr/mdec/bootxx_ffsv1 529. 530.Pp 531Create a bootable FAT file system on 532.Sq wd1a , 533which should have the same offset and size as a FAT primary partition 534in the Master Boot Record (MBR): 535.Dl Ic newfs_msdos -r 16 /dev/rwd1a 536.Bd -ragged -offset indent-two -compact 537.Em Notes: 538The 539.Fl r Ar 16 540is to reserve space for the primary bootstrap. 541.Xr newfs_msdos 8 542will display an 543.Dq MBR type 544such as 545.Ql 1 , 546.Ql 4 , 547or 548.Ql 6 ; 549the MBR partition type of the appropriate primary partition should be 550changed to this value. 551.Ed 552.Dl Ic mount -t msdos /dev/wd1a /mnt 553.Dl Ic cp /usr/mdec/boot /mnt/boot 554.Dl Ic cp path/to/kernel /mnt/netbsd 555.Dl Ic umount /mnt 556.Dl Ic installboot -t raw /dev/rwd1a /usr/mdec/bootxx_msdos 557.Bd -ragged -offset indent-two -compact 558.Em Note: 559It may be necessary to ensure that there is a valid 560.Nx 561disklabel on 562.Sq wd1 563for the primary bootstrap to function correctly. 564.Ed 565. 566.Ss NetBSD/next68k 567Install the bootstrap on to disk 568.Sq sd0 : 569.Dl Ic installboot /dev/rsd0c /usr/mdec/boot 570.Pp 571. 572.Ss NetBSD/pmax 573Install the Berkeley Fast File System primary bootstrap on to disk 574.Sq sd0 : 575.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 576.Pp 577.Nx Ns Tn /pmax 578requires that this file system starts at block 0 of the disk. 579.Pp 580Install the ISO 9660 primary bootstrap in the file 581.Pa /tmp/cd-image : 582.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 583.Pp 584Make an ISO 9660 filesystem in the file 585.Pa /tmp/cd-image 586and install the ISO 9660 primary bootstrap in the filesystem, where the 587source directory for the ISO 9660 filesystem contains a kernel, the 588primary bootstrap 589.Pa bootxx_cd9660 590and the secondary bootstrap 591.Pa boot.pmax : 592.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 593.Dl ... 594.Dl 48 51 iso-source-dir/bootxx_cd9660 595.Dl ... 596.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 597. 598.Ss NetBSD/sparc 599Install the Berkeley Fast File System primary bootstrap on to disk 600.Sq sd0 , 601with the secondary bootstrap 602.Sq Pa /boot 603already present: 604.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 605. 606.Ss NetBSD/sparc64 607Install the Berkeley Fast File System primary bootstrap on to disk 608.Sq wd0 : 609.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk 610.Pp 611The secondary 612.Nx Ns Tn /sparc64 613bootstrap is located in 614.Pa /usr/mdec/ofwboot . 615. 616.Ss NetBSD/sun2 and NetBSD/sun3 617Install the Berkeley Fast File System primary bootstrap on to disk 618.Sq sd0 , 619with the secondary bootstrap 620.Sq Pa /boot 621already present: 622.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 623. 624.Sh SEE ALSO 625.Xr uname 3 , 626.Xr boot 8 , 627.Xr disklabel 8 628. 629.Sh HISTORY 630This implementation of 631.Nm 632appeared in 633.Nx 1.6 . 634. 635.Sh AUTHORS 636The machine independent portion of this implementation of 637.Nm 638was written by Luke Mewburn. 639The following people contributed to the various machine dependent 640back-ends: 641Simon Burge (pmax), 642Chris Demetriou (alpha), 643Matthew Fredette (sun2, sun3), 644Matthew Green (sparc64), 645Ross Harvey (alpha), 646Michael Hitch (amiga), 647Paul Kranenburg (sparc), 648David Laight (i386), 649Christian Limpach (next68k), 650Luke Mewburn (macppc), 651Matt Thomas (vax), 652and 653Izumi Tsutsui (news68k, newsmips). 654. 655.Sh BUGS 656There are not currently primary bootstraps to support all file systems 657types which are capable of being the root file system. 658. 659.Ss NetBSD/alpha 660The 661.Nx Ns Tn /alpha 662primary bootstrap program can only load the secondary bootstrap program 663from file systems starting at the beginning (block 0) of disks. 664Similarly, the secondary bootstrap program can only load kernels from 665file systems starting at the beginning of disks. 666.Pp 667The size of primary bootstrap programs is restricted to 7.5KB, even 668though some file systems (e.g., ISO 9660) are able to accommodate larger 669ones. 670. 671.Ss NetBSD/hp300 672The disk must have a boot partition large enough to hold the bootstrap code. 673Currently the primary bootstrap must be a LIF format file. 674. 675.Ss NetBSD/i386 and NetBSD/amd64 676The bootstrap must be installed in the 677.Nx 678partition that starts at the beginning of the mbr partition. 679If that is a valid filesystem and contains the 680.Pa /boot 681program then it will be used as the root filesystem, otherwise the 682.Sq a 683partition will be booted. 684.Pp 685The size of primary bootstrap programs is restricted to 8KB, even 686though some file systems (e.g., ISO 9660) are able to accommodate larger 687ones. 688. 689.Ss NetBSD/next68k 690The size of bootstrap programs is restricted to the free space before 691the file system at the beginning of the disk minus 8KB. 692. 693.Ss NetBSD/pmax 694The 695.Nx Ns Tn /pmax 696secondary bootstrap program can only load kernels from file 697systems starting at the beginning of disks. 698.Pp 699The size of primary bootstrap programs is restricted to 7.5KB, even 700though some file systems (e.g., ISO 9660) are able to accommodate larger 701ones. 702. 703.Ss NetBSD/sun2 and NetBSD/sun3 704The 705.Nx Ns Tn /sun2 706and 707.Nx Ns Tn /sun3 708secondary bootstrap program can only load kernels from file 709systems starting at the beginning of disks. 710. 711.Ss NetBSD/vax 712The 713.Nx Ns Tn /vax 714secondary bootstrap program can only load kernels from file systems 715starting at the beginning of disks. 716.Pp 717The size of primary bootstrap programs is restricted to 7.5KB, even 718though some file systems (e.g., ISO 9660) are able to accommodate larger 719ones. 720