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