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