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