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