1.\" $NetBSD: installboot.8,v 1.43 2004/08/15 22:00:12 dsl 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 June 25, 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 amd64 , 134.Sy amiga , 135.Sy i386 , 136.Sy pmax , 137.Sy sparc64 , 138and 139.Sy vax . 140.Pp 141The following platform does not require the first step since a 142single bootstrap file is used. 143The single bootstrap is installed like the primary bootstrap on 144other platforms: 145.Sy next68k . 146.Pp 147.El 148.Pp 149The options and arguments recognized by 150.Nm 151are as follows: 152. 153.Bl -tag -width "optionsxxx" 154. 155.It Fl b Ar s1bno 156Install 157.Ar primary 158at block number 159.Ar s1bno 160instead of the default location for the machine and file system type. 161.Sy [ alpha , 162.Sy pmax , 163.Sy vax ] 164. 165.It Fl B Ar s2bno 166When hard-coding the blocks of 167.Ar secondary 168into 169.Ar primary , 170start from block 171.Ar s2bno 172instead of trying to determine the block numbers occupied by 173.Ar secondary 174by examining 175.Ar filesystem . 176If this option is supplied, 177.Ar secondary 178should refer to an actual secondary bootstrap (rather than the 179file name of the one present in 180.Ar filesystem ) 181so that its size can be determined. 182. 183.It Fl c 184Clear (remove) any existing bootstrap instead of installing one. 185. 186.It Fl m Ar machine 187Use 188.Ar machine 189as the target machine type. 190The default machine is determined from 191.Xr uname 3 192and then 193.Ev MACHINE . 194The following machines are currently supported by 195.Nm : 196.Bd -ragged -offset indent 197.Sy alpha , 198.Sy amd64 , 199.Sy amiga , 200.Sy hp300 , 201.Sy i386 , 202.Sy macppc , 203.Sy news68k , 204.Sy newsmips , 205.Sy next68k , 206.Sy pmax , 207.Sy sparc , 208.Sy sparc64 , 209.Sy sun2 , 210.Sy sun3 , 211.Sy vax , 212.Sy x68k 213.Ed 214. 215. 216.It Fl n 217Do not write to 218.Ar filesystem . 219. 220.It Fl o Ar options 221Machine specific 222.Nm 223options, comma separated. 224.Pp 225Supported options are (with the machines for they are valid in brackets): 226. 227.Bl -tag -offset indent -width alphasum 228. 229.It Sy alphasum 230.Sy [ alpha ] 231Recalculate and restore the Alpha checksum. 232This is the default for 233.Nx Ns Tn /alpha . 234. 235.It Sy append 236.Sy [ alpha , 237.Sy pmax , 238.Sy vax ] 239Append 240.Ar primary 241to the end of 242.Ar filesystem , 243which must be a regular file in this case. 244. 245.It Sy command=\*[Lt]boot command\*[Gt] 246.Sy [ amiga ] 247Modify the default boot command line. 248. 249.It Sy console=\*[Lt]console name\*[Gt] 250.Sy [ amd64 , 251.Sy i386 ] 252Set the console device, \*[Lt]console name\*[Gt] must be one of: 253pc, com0, com1, com2, com3, com0kbd, com1kbd, com2kbd or com3kbd. 254. 255.It Sy ioaddr=\*[Lt]ioaddr\*[Gt] 256.Sy [ amd64 , 257.Sy i386 ] 258Set the IO address to be used for the console serial port. 259Defaults to the IO address used by the system BIOS for the specified port. 260. 261.It Sy keymap=\*[Lt]keymap\*[Gt] 262.Sy [ amd64 , 263.Sy i386 ] 264Set a boot time keyboard translation map. 265Each character in \*[Lt]keymap\*[Gt] will be replaced by the one following it. 266For example, an argument of 267.Dq zyz 268would swap the lowercase letters 269.Sq y 270and 271.Sq z . 272. 273.It Sy password=\*[Lt]password\*[Gt] 274.Sy [ amd64 , 275.Sy i386 ] 276Set the password which must be entered before the boot menu can be accessed. 277. 278.It Sy resetvideo 279.Sy [ amd64 , 280.Sy i386 ] 281Reset the video before booting. 282. 283.It Sy speed=\*[Lt]baud rate\*[Gt] 284.Sy [ amd64 , 285.Sy i386 ] 286Set the baud rate for the serial console. 287. 288.It Sy sunsum 289.Sy [ alpha , 290.Sy pmax , 291.Sy vax ] 292Recalculate and restore the Sun and 293.Nx Ns Tn /sparc 294compatible checksum. 295.Em Note : 296The existing 297.Nx Ns Tn /sparc 298disklabel should use no more than 4 partitions. 299. 300.It Sy timeout=\*[Lt]seconds\*[Gt] 301.Sy [ amd64 , 302.Sy i386 ] 303Set the timeout before the automatic boot begins to the given number of seconds. 304.El 305. 306.It Fl t Ar fstype 307Use 308.Ar fstype 309as the type of 310.Ar filesystem . 311The default operation is to attempt to auto-detect this setting. 312The following file system types are currently supported by 313.Nm : 314. 315.Bl -tag -offset indent -width ffs 316. 317.It Sy ffs 318.Bx 319Fast File System. 320. 321.It Sy raw 322.Sq Raw 323image. 324Note: if a platform needs to hard-code the block offset of the secondary 325bootstrap, it cannot be searched for on this file system type, and must 326be provided with 327.Fl B Ar s2bno . 328.El 329. 330.It Fl v 331Verbose operation. 332. 333.It Ar filesystem 334The path name of the device or file system image that 335.Nm 336is to operate on. 337It is not necessary for 338.Ar filesystem 339to be a currently mounted file system. 340. 341.It Ar primary 342The path name of the 343.Dq primary 344boot block to install. 345. 346.It Ar secondary 347The path name of the 348.Dq secondary 349boot block, 350relative to the top of 351.Ar filesystem . 352Most systems require 353.Ar secondary 354to be in the 355.Dq root 356directory of the file system, so the leading 357.Dq Pa / 358is not necessary on 359.Ar secondary . 360.Pp 361Only certain combinations of 362platform 363.Pq Fl m Ar machine 364and file system type 365.Pq Fl t Ar fstype 366require that the name of the secondary bootstrap is 367supplied as 368.Ar secondary , 369so that information such as the disk block numbers occupied 370by the secondary bootstrap can be stored in the primary bootstrap. 371These are: 372.Bl -column "Platform" "File systems" -offset indent 373.It Sy "Platform" Ta Sy "File systems" 374.It macppc Ta ffs, raw 375.It news68k Ta ffs, raw 376.It newsmips Ta ffs, raw 377.It sparc Ta ffs, raw 378.It sun2 Ta ffs, raw 379.It sun3 Ta ffs, raw 380.El 381.El 382.Pp 383.Nm 384exits 0 on success, and \*[Gt]0 if an error occurs. 385. 386.Sh ENVIRONMENT 387.Nm 388uses the following environment variables: 389. 390.Bl -tag -width "MACHINE" 391. 392.It Ev MACHINE 393Default value for 394.Ar machine , 395overriding the result from 396.Xr uname 3 . 397. 398.El 399. 400.Sh FILES 401Most 402.Nx 403ports will contain variations of the following files: 404.Pp 405.Bl -tag -width /usr/mdec/bootxx_ustarfs 406. 407.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE 408Primary bootstrap for file system type 409.Sy FSTYPE . 410Installed into the bootstrap area of the file system by 411.Nm . 412. 413.It Pa /usr/mdec/bootxx_ffsv1 414Primary bootstrap for 415.Sy FFSv1 416file systems 417(the "traditional" 418.Nx 419file system). 420. 421.It Pa /usr/mdec/bootxx_ffsv2 422Primary bootstrap for 423.Sy FFSv2 424file systems. 425. 426.It Pa /usr/mdec/bootxx_lfsv1 427Primary bootstrap for 428.Sy LFSv1 429file systems. 430. 431.It Pa /usr/mdec/bootxx_lfsv2 432Primary bootstrap for 433.Sy LFSv2 434file systems 435(the default LFS version). 436. 437.It Pa /usr/mdec/bootxx_msdos 438Primary bootstrap for 439.Tn MS-DOS 440.Sy FAT 441file systems. 442. 443.It Pa /usr/mdec/bootxx_ustarfs 444Primary bootstrap for 445.Sy TARFS 446boot images. 447This is used by various install media. 448. 449.It Pa /usr/mdec/boot. Ns Sy MACHINE 450Secondary bootstrap for machine type 451.Sy MACHINE . 452This should be installed into the file system before 453.Nm 454is run. 455. 456.It Pa /usr/mdec/boot 457Synonym for 458.Pa /usr/mdec/boot. Ns Sy MACHINE 459. 460.It Pa /boot. Ns Sy MACHINE 461Installed copy of secondary bootstrap for machine type 462.Sy MACHINE . 463. 464.It Pa /boot 465Installed copy of secondary bootstrap. 466Searched for by the primary bootstrap if 467.Pa /boot. Ns Sy MACHINE 468is not found. 469. 470.El 471. 472.Ss NetBSD/next68k files 473. 474.Bl -tag -width /usr/mdec/bootxx_ustarfs 475. 476.It Pa /usr/mdec/boot 477.Nx Ns Tn /next68k 478bootstrap. 479. 480.El 481. 482.Ss NetBSD/sparc64 files 483. 484.Bl -tag -width /usr/mdec/bootxx_ustarfs 485. 486.It Pa /usr/mdec/bootblk 487.Nx Ns Tn /sparc64 488primary bootstrap. 489. 490.It Pa /usr/mdec/ofwboot 491.Nx Ns Tn /sparc64 492secondary bootstrap. 493. 494.It Pa /ofwboot 495Installed copy of 496.Nx Ns Tn /sparc64 497secondary bootstrap. 498. 499.El 500. 501.Sh EXAMPLES 502. 503.Ss common 504Verbosely install the Berkeley Fast File System primary bootstrap on to disk 505.Sq sd0 : 506.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs 507.Pp 508Remove the primary bootstrap from disk 509.Sq sd1 : 510.Dl Ic installboot -c /dev/rsd1c 511. 512.Ss NetBSD/amiga 513Modify the command line to change the default from "netbsd -ASn2" to 514"netbsd -S": 515.Dl Ic installboot -m amiga -o command="netbsd -S" /dev/rsd0a /usr/mdec/bootxx_ffs 516. 517.Ss NetBSD/i386 and NetBSD/amd64 518Install new boot blocks on an existing mounted root file system on 519.Sq wd0 , 520setting the timeout to five seconds, after copying a new secondary 521bootstrap: 522.Dl Ic cp /usr/mdec/boot /boot 523.Dl Ic installboot -v -o timeout=5 /dev/rwd0a /usr/mdec/bootxx_ffsv1 524. 525.Pp 526Create a bootable floppy disk with an FFSv1 527file system for a small custom kernel (note: bigger kernels needing 528multiple disks are handled with the ustarfs file system): 529.Dl Ic newfs -s 1440k /dev/rfd0a 530.Bd -ragged -offset indent-two -compact 531.Em Note: 532Ignore the warnings that 533.Xr newfs 8 534displays; it can not write a disklabel, 535which is not a problem for a floppy disk. 536.Ed 537.Dl Ic mount /dev/fd0a /mnt 538.Dl Ic cp /usr/mdec/boot /mnt/boot 539.Dl Ic gzip -9 \*[Lt] sys/arch/i386/compile/mykernel/netbsd \*[Gt] /mnt/netbsd.gz 540.Dl Ic umount /mnt 541.Dl Ic installboot -v /dev/rfd0a /usr/mdec/bootxx_ffsv1 542. 543.Pp 544Create a bootable FAT file system on 545.Sq wd1a , 546which should have the same offset and size as a FAT primary partition 547in the Master Boot Record (MBR): 548.Dl Ic newfs_msdos -r 16 /dev/rwd1a 549.Bd -ragged -offset indent-two -compact 550.Em Notes: 551The 552.Fl r Ar 16 553is to reserve space for the primary bootstrap. 554.Xr newfs_msdos 8 555will display an 556.Dq MBR type 557such as 558.Ql 1 , 559.Ql 4 , 560or 561.Ql 6 ; 562the MBR partition type of the appropriate primary partition should be 563changed to this value. 564.Ed 565.Dl Ic mount -t msdos /dev/wd1a /mnt 566.Dl Ic cp /usr/mdec/boot /mnt/boot 567.Dl Ic cp path/to/kernel /mnt/netbsd 568.Dl Ic umount /mnt 569.Dl Ic installboot -t raw /dev/rwd1a /usr/mdec/bootxx_msdos 570.Bd -ragged -offset indent-two -compact 571.Em Note: 572It may be necessary to ensure that there is a valid 573.Nx 574disklabel on 575.Sq wd1 576for the primary bootstrap to function correctly. 577.Ed 578. 579.Ss NetBSD/next68k 580Install the bootstrap on to disk 581.Sq sd0 : 582.Dl Ic installboot /dev/rsd0c /usr/mdec/boot 583.Pp 584. 585.Ss NetBSD/pmax 586Install the Berkeley Fast File System primary bootstrap on to disk 587.Sq sd0 : 588.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 589.Pp 590.Nx Ns Tn /pmax 591requires that this file system starts at block 0 of the disk. 592.Pp 593Install the ISO 9660 primary bootstrap in the file 594.Pa /tmp/cd-image : 595.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 596.Pp 597Make an ISO 9660 filesystem in the file 598.Pa /tmp/cd-image 599and install the ISO 9660 primary bootstrap in the filesystem, where the 600source directory for the ISO 9660 filesystem contains a kernel, the 601primary bootstrap 602.Pa bootxx_cd9660 603and the secondary bootstrap 604.Pa boot.pmax : 605.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 606.Dl ... 607.Dl 48 51 iso-source-dir/bootxx_cd9660 608.Dl ... 609.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 610. 611.Ss NetBSD/sparc 612Install the Berkeley Fast File System primary bootstrap on to disk 613.Sq sd0 , 614with the secondary bootstrap 615.Sq Pa /boot 616already present: 617.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 618. 619.Ss NetBSD/sparc64 620Install the Berkeley Fast File System primary bootstrap on to disk 621.Sq wd0 : 622.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk 623.Pp 624The secondary 625.Nx Ns Tn /sparc64 626bootstrap is located in 627.Pa /usr/mdec/ofwboot . 628. 629.Ss NetBSD/sun2 and NetBSD/sun3 630Install the Berkeley Fast File System primary bootstrap on to disk 631.Sq sd0 , 632with the secondary bootstrap 633.Sq Pa /boot 634already present: 635.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 636. 637.Sh SEE ALSO 638.Xr uname 3 , 639.Xr boot 8 , 640.Xr disklabel 8 641. 642.Sh HISTORY 643This implementation of 644.Nm 645appeared in 646.Nx 1.6 . 647. 648.Sh AUTHORS 649The machine independent portion of this implementation of 650.Nm 651was written by Luke Mewburn. 652The following people contributed to the various machine dependent 653back-ends: 654Simon Burge (pmax), 655Chris Demetriou (alpha), 656Matthew Fredette (sun2, sun3), 657Matthew Green (sparc64), 658Ross Harvey (alpha), 659Michael Hitch (amiga), 660Paul Kranenburg (sparc), 661David Laight (i386), 662Christian Limpach (next68k), 663Luke Mewburn (macppc), 664Matt Thomas (vax), 665and 666Izumi Tsutsui (news68k, newsmips). 667. 668.Sh BUGS 669There are not currently primary bootstraps to support all file systems 670types which are capable of being the root file system. 671. 672.Ss NetBSD/alpha 673The 674.Nx Ns Tn /alpha 675primary bootstrap program can only load the secondary bootstrap program 676from file systems starting at the beginning (block 0) of disks. 677Similarly, the secondary bootstrap program can only load kernels from 678file systems starting at the beginning of disks. 679.Pp 680The size of primary bootstrap programs is restricted to 7.5KB, even 681though some file systems (e.g., ISO 9660) are able to accommodate larger 682ones. 683. 684.Ss NetBSD/hp300 685The disk must have a boot partition large enough to hold the bootstrap code. 686Currently the primary bootstrap must be a LIF format file. 687. 688.Ss NetBSD/i386 and NetBSD/amd64 689The bootstrap must be installed in the 690.Nx 691partition that starts at the beginning of the mbr partition. 692If that is a valid filesystem and contains the 693.Pa /boot 694program then it will be used as the root filesystem, otherwise the 695.Sq a 696partition will be booted. 697.Pp 698The size of primary bootstrap programs is restricted to 8KB, even 699though some file systems (e.g., ISO 9660) are able to accommodate larger 700ones. 701. 702.Ss NetBSD/next68k 703The size of bootstrap programs is restricted to the free space before 704the file system at the beginning of the disk minus 8KB. 705. 706.Ss NetBSD/pmax 707The 708.Nx Ns Tn /pmax 709secondary bootstrap program can only load kernels from file 710systems starting at the beginning of disks. 711.Pp 712The size of primary bootstrap programs is restricted to 7.5KB, even 713though some file systems (e.g., ISO 9660) are able to accommodate larger 714ones. 715. 716.Ss NetBSD/sun2 and NetBSD/sun3 717The 718.Nx Ns Tn /sun2 719and 720.Nx Ns Tn /sun3 721secondary bootstrap program can only load kernels from file 722systems starting at the beginning of disks. 723. 724.Ss NetBSD/vax 725The 726.Nx Ns Tn /vax 727secondary bootstrap program can only load kernels from file systems 728starting at the beginning of disks. 729.Pp 730The size of primary bootstrap programs is restricted to 7.5KB, even 731though some file systems (e.g., ISO 9660) are able to accommodate larger 732ones. 733