1.\" $NetBSD: installboot.8,v 1.108 2023/12/26 06:00:35 mrg Exp $ 2.\" 3.\" Copyright (c) 2002-2023 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30. 31.\" Prevent accidental hyphenation after the hyphen in "U-Boot" 32.\" Usage: \*(UB 33.ds UB U\(hyBoot 34. 35.Dd December 25, 2023 36.Dt INSTALLBOOT 8 37.Os 38.Sh NAME 39.Nm installboot 40.Nd install disk bootstrap software 41. 42.Sh SYNOPSIS 43.Nm 44.Op Fl fnv 45.Op Fl B Ar s2bno 46.Op Fl b Ar s1bno 47.Op Fl m Ar machine 48.Op Fl o Ar options 49.Op Fl t Ar fstype 50.Op Fl u Ar U-Boot-paths 51.Ar filesystem 52.Ar primary 53.Op Ar secondary 54.Nm 55.Fl c 56.Op Fl fnv 57.Op Fl m Ar machine 58.Op Fl o Ar options 59.Op Fl t Ar fstype 60.Ar filesystem 61.Nm 62.Fl e 63.Op Fl fnv 64.Op Fl m Ar machine 65.Op Fl o Ar options 66.Ar bootstrap 67. 68.Sh DESCRIPTION 69The 70.Nm 71utility installs and removes 72.Nx 73disk bootstrap software into a file system. 74.Nm 75can install 76.Ar primary 77into 78.Ar filesystem , 79or disable an existing bootstrap in 80.Ar filesystem . 81.Ss Traditional NetBSD boot 82Generally, 83.Nx 84disk bootstrap software consists of two parts: a 85.Dq primary 86bootstrap program usually written into the disklabel area of the 87file system by 88.Nm , 89and a 90.Dq secondary 91bootstrap program that usually resides as an ordinary file in the file system. 92.Pp 93When booting, the primary bootstrap program is loaded and invoked by 94the machine's 95.Tn PROM 96or 97.Tn BIOS . 98After receiving control of the system it loads and runs the secondary 99bootstrap program, which in turn loads and runs the kernel. 100The secondary bootstrap may allow control over various boot parameters 101passed to the kernel. 102.Pp 103Perform the following steps to make a file system bootable: 104.Bl -enum 105.It 106Copy the secondary bootstrap 107.Po 108usually 109.Pa /usr/mdec/boot. Ns Aq Ar MACHINE\^ 110or 111.Pa /usr/mdec/boot 112.Pc 113to the root directory of the target file system. 114. 115.It 116Use 117.Nm 118to install the primary bootstrap program 119.Po 120usually 121.Pa /usr/mdec/bootxx_ Ns Aq Ar FSTYPE\^ 122.Pc 123into 124.Ar filesystem . 125.Pp 126The following platforms do not require this step if the primary bootstrap 127already exists and the secondary bootstrap file is just being updated: 128.Sy alpha , 129.Sy amd64 , 130.Sy amiga , 131.Sy i386 , 132.Sy pmax , 133.Sy sparc64 , 134and 135.Sy vax . 136.Pp 137The following platform does not require the first step since a 138single bootstrap file is used. 139The single bootstrap is installed like the primary bootstrap on 140other platforms: 141.Sy next68k . 142.El 143.Pp 144On some architectures the options of an existing installed bootstrap, 145or those of a bootstrap file can be changed. 146Installing a new primary bootstrap will reset those options to default 147values. 148.Ss Embedded board types 149Some platforms, typically embedded system platforms, are umbrella platforms 150that support many different individual board types, each with their own 151boot loader binary and installation procedure requirements. 152On these platforms, it may be necessary to provide specific board type 153information to 154.Nm . 155Information about known boards and their requirements is loaded from a 156database at run-time. 157Sometimes these platforms also require the use of 3rd-party boot loader 158software, such as \*(UB. 159To support these platforms, 160.Nm 161scans known locations for these 3rd-party boot loader packages for 162database overlays that contain additional board-specific boot loader 163installation information in a file called 164.Pa installboot.plist . 165.Pp 166The following platforms have this requirement and utilize this database 167overlay feature: 168.Sy evbarm . 169.Ss UEFI boot 170On platforms that boot with 171.Tn UEFI , 172there is a single boot loader in the 173.Tn EFI 174system partition at 175.Pa EFI/boot/boot Ns Ao Ar ARCH\^ Ac Ns Pa .efi 176where 177.Ar ARCH 178is the 179.Tn UEFI 180name for the architecture, such as 181.Li ia32 182.Pq Nx Ns /i386 , 183.Li x64 184.Pq Nx Ns /amd64 , 185or 186.Li aa64 187.Pq Nx Ns /aarch64 . 188.Pp 189.Nm 190is not needed for 191.Tn UEFI 192boot. 193However, it may be used on a platform that supports 194.Tn UEFI 195boot to make a 196hybrid image that can be booted 197.Em either 198with 199.Tn UEFI 200boot or with, e.g., 201.Tn BIOS 202or \*(UB. 203Hybrid images may also require a special 204.Tn GPT 205for 206.Tn BIOS 207boot; see 208.Xr gpt 8 . 209.Ss Options 210The options and arguments recognized by 211.Nm 212are as follows: 213. 214.Bl -tag -width Fl 215. 216.It Fl B Ar s2bno 217When hard-coding the blocks of 218.Ar secondary 219into 220.Ar primary , 221start from block 222.Ar s2bno 223instead of trying to determine the block numbers occupied by 224.Ar secondary 225by examining 226.Ar filesystem . 227If this option is supplied, 228.Ar secondary 229should refer to an actual secondary bootstrap 230.Po 231rather than the file name of the one present in 232.Ar filesystem 233.Pc 234so that its size can be determined. 235. 236.It Fl b Ar s1bno 237Install 238.Ar primary 239at block number 240.Ar s1bno 241instead of the default location for the machine and file system type. 242.Sy [ alpha , 243.Sy i386/amd64 244.Po 245.Pa bootxx_fat16 246only 247.Pc , 248.Sy pmax , 249.Sy vax ] 250. 251.It Fl c 252Clear (remove) any existing bootstrap instead of installing one. 253. 254.It Fl e 255Edit the options of an existing bootstrap. 256This can be used to change the options in 257.Pa bootxx_ Ns Aq Ar FSTYPE\^ 258files, 259raw disk partitions, and the 260.Pa pxeboot_ia32.bin 261file. 262With 263.Fl v 264and without 265.Fl o , 266show the current options. 267.Sy [ amd64 , i386 ] 268. 269.It Fl f 270Forces 271.Nm 272to ignore some errors. 273. 274.It Fl m Ar machine 275Use 276.Ar machine 277as the target machine type. 278The default machine is determined from 279.Xr uname 3 280and then 281.Ev MACHINE 282environment variable. 283The following machines are currently supported: 284.Bd -ragged -offset indent 285.Ic alpha , 286.Ic amd64 , 287.Ic amiga , 288.Ic evbarm , 289.Ic ews4800mips , 290.Ic hp300 , 291.Ic hppa , 292.Ic i386 , 293.Ic landisk , 294.Ic macppc , 295.Ic news68k , 296.Ic newsmips , 297.Ic next68k , 298.Ic pmax , 299.Ic sparc , 300.Ic sparc64 , 301.Ic sun2 , 302.Ic sun3 , 303.Ic vax , 304.Ic x68k 305.Ed 306. 307. 308.It Fl n 309Do not write to 310.Ar filesystem . 311. 312.It Fl o Ar options 313Machine specific 314.Nm 315options, comma separated. 316.Pp 317Supported options are 318.Pq with the machines for they are valid in brackets : 319. 320.Bl -tag -width Ic 321. 322.It Ic alphasum 323.Sy [ alpha ] 324Recalculate and restore the Alpha checksum. 325This is the default for 326.Nx Ns /alpha . 327. 328.It Ic append 329.Sy [ alpha , 330.Sy pmax , 331.Sy vax ] 332Append 333.Ar primary 334to the end of 335.Ar filesystem , 336which must be a regular file in this case. 337. 338.It Ic board Ns Op Ns Li = Ns Ar type 339.Sy [ evbarm ] 340Specify the board type used to determine the correct boot loader image 341and installation procedure. 342If omitted, 343.Nm 344will attempt to guess the board type based on system information if run 345natively. 346. 347.It Ic bootconf 348.Sy [ amd64 , 349.Sy i386 ] 350(Don't) read a 351.Pa boot.cfg 352file. 353. 354.It Ic command Ns Li = Ns Ar commandline 355.Sy [ amiga ] 356Modify the default boot command line. 357. 358.It Ic console Ns Li = Ns Ar name 359.Sy [ amd64 , 360.Sy i386 ] 361Set the console device. 362.Ar name 363must be one of: 364.Ic pc , 365.Ic com0 , 366.Ic com1 , 367.Ic com2 , 368.Ic com3 , 369.Ic com0kbd , 370.Ic com1kbd , 371.Ic com2kbd , 372.Ic com3kbd , 373or 374.Ic auto . 375. 376.It Ic dtb Ns Li = Ns Ar dtbfile 377.Sy [ evbarm ] 378Attempt to determine the board type from information in the device tree 379blob file at 380.Ar dtbfile . 381If both 382.Ic board 383and 384.Ic dtb 385options are specified, 386.Ic board 387takes precendence. 388. 389.It Ic ioaddr Ns Li = Ns Ar ioaddr 390.Sy [ amd64 , 391.Sy i386 ] 392Set the IO address to be used for the console serial port. 393Defaults to the IO address used by the system 394.Tn BIOS 395for the specified port. 396. 397.It Ic keymap Ns Li = Ns Ar keymap 398.Sy [ amd64 , 399.Sy i386 ] 400Set a boot time keyboard translation map. 401Each character in 402.Ar keymap 403will be replaced by the one following it. 404For example, an argument of 405.Li zyz 406would swap the lowercase letters 407.Aq y 408and 409.Aq z . 410. 411.It Ic media Ns Li = Ns Ar type 412.Sy [ evbarm ] 413Some boards require a different boot loader binary and/or installation 414procedure depending on what type of media will be used to boot the system. 415For such boards, this option is required, and omitting it will display a 416usage message that lists the valid media types for the board. 417For boards that do not require special media handling, this option is 418not allowed. 419Common values: 420.Ic sdmmc , 421.Ic emmc , 422.Ic usb . 423. 424.It Ic modules 425.Sy [ amd64 , 426.Sy i386 ] 427(Don't) load kernel modules. 428. 429.It Ic password Ns Li = Ns Ar password 430.Sy [ amd64 , 431.Sy i386 ] 432Set the password which must be entered before the boot menu can be accessed. 433. 434.It Ic resetvideo 435.Sy [ amd64 , 436.Sy i386 ] 437Reset the video before booting. 438. 439.It Ic speed Ns Li = Ns Ar baud 440.Sy [ amd64 , 441.Sy i386 ] 442Set the baud rate for the serial console. 443If a value of zero is specified, then the current baud rate (set by the 444.Tn BIOS ) 445will be used. 446. 447.It Ic sunsum 448.Sy [ alpha , 449.Sy pmax , 450.Sy vax ] 451Recalculate and restore the Sun and 452.Nx Ns /sparc 453compatible checksum. 454.Em Note : 455The existing 456.Nx Ns /sparc 457disklabel should use no more than 4 partitions. 458. 459.It Ic timeout Ns Li = Ns Ar seconds 460.Sy [ amd64 , 461.Sy i386 ] 462Set the timeout before the automatic boot begins to the given number of seconds. 463.El 464. 465.It Fl t Ar fstype 466Use 467.Ar fstype 468as the type of 469.Ar filesystem . 470The default operation is to attempt to auto-detect this setting. 471The following file system types are currently supported by: 472. 473.Bl -tag -width Ic 474. 475.It Ic ffs 476.Bx 477Fast File System. 478. 479.It Ic raid 480Mirrored RAIDframe File System. 481. 482.It Ic raw 483.Dq Raw 484image. 485.Em Note : 486if a platform needs to hard-code the block offset of the secondary 487bootstrap, it cannot be searched for on this file system type, and must 488be provided with 489.Fl B Ar s2bno . 490.El 491. 492.It Fl u Ar U-Boot-paths 493.Ar U-Boot-paths 494is a colon-separated list of search paths to scan for 495\*(UB packages with 496.Nm 497installation overlays. 498If multiple overlays are found, overlays from paths closer to the front 499of the list take precedence. 500If not specified, environment variable 501.Ev INSTALLBOOT_UBOOT_PATHS 502is used if defined; otherwise, the default path is 503.Pa /usr/pkg/share/u-boot . 504This option is only used on platforms that support 505using \*(UB. 506. 507.It Fl v 508Verbose operation. 509. 510.It Ar filesystem 511The path name of the device or file system image that 512.Nm 513is to operate on. 514It is not necessary for 515.Ar filesystem 516to be a currently mounted file system. 517. 518.It Ar primary 519The path name of the 520.Dq primary 521boot block to install. 522The path name must refer to a file in a file system that is currently 523mounted. 524. 525.It Ar secondary 526The path name of the 527.Dq secondary 528boot block, relative to the root of 529the file system in the device or image specified by the 530.Ar filesystem 531argument. 532Note that this may refer to a file in a file system that is not mounted. 533Most systems require 534.Ar secondary 535to be in the 536.Dq root 537directory of the file system, so the leading 538.Ql / 539is not necessary on 540.Ar secondary . 541.Pp 542Only certain combinations of 543platform 544.Pq Fl m Ar machine 545and file system type 546.Pq Fl t Ar fstype 547require that the name of the secondary bootstrap is 548supplied as 549.Ar secondary , 550so that information such as the disk block numbers occupied 551by the secondary bootstrap can be stored in the primary bootstrap. 552These are: 553.Bl -column "Platform" "File systems" -offset indent 554.It Sy "Platform" Ta Sy "File systems" 555.It macppc Ta ffs, raw 556.It news68k Ta ffs, raw 557.It newsmips Ta ffs, raw 558.It sparc Ta ffs, raid, raw 559.It sun2 Ta ffs, raw 560.It sun3 Ta ffs, raw 561.El 562.El 563. 564.Sh ENVIRONMENT 565.Bl -tag -width Ev 566. 567.It Ev INSTALLBOOT_UBOOT_PATHS 568A colon-separated list of search paths to scan for 569\*(UB packages with 570.Nm 571installation overlays. 572If multiple overlays are found, overlays from paths closer to the front 573of the list take precedence. 574If not specified, the default path is 575.Pa /usr/pkg/share/u-boot . 576This environment variable is only used on platforms that support 577using \*(UB. 578. 579.It Ev MACHINE 580Default value for 581.Ar machine , 582overriding the result from 583.Xr uname 3 . 584. 585.El 586. 587.Sh FILES 588Most 589.Nx 590ports will contain variations of the following files: 591.Bl -tag -width Pa 592. 593.It Pa /usr/mdec/bootxx_ Ns Aq Ar FSTYPE\^ 594Primary bootstrap for file system type 595.Ar FSTYPE . 596Installed into the bootstrap area of the file system by 597.Nm . 598. 599.It Pa /usr/mdec/bootxx_fat16 600Primary bootstrap for 601.Tn MS-DOS 602.Sy FAT16 603file systems. 604This differs from 605.Pa bootxx_msdos 606in that it doesn't require the filesystem to have been initialised with 607any 608.Dq reserved sectors . 609It also uses the information in the 610.Dq Boot Parameter Block 611to get the media and filesystem properties. 612The 613.Dq hidden sectors 614field of the 615.Tn BPB 616must be the offset of the partition in the disk. 617This can be set using the 618.Fl b Ar s1bno 619option. 620. 621.It Pa /usr/mdec/bootxx_ffsv1 622Primary bootstrap for 623.Sy FFSv1 624file systems 625.Po 626the 627.Dq traditional 628file system prior to 629.Nx 6.0 630.Pc . 631Use 632.Xr dumpfs 8 633to confirm the file system format is FFSv1. 634. 635.It Pa /usr/mdec/bootxx_ffsv2 636Primary bootstrap for 637.Sy FFSv2 638file systems 639.Po 640the default file system for some platforms as of 641.Nx 6.0 642.Pc . 643Use 644.Xr dumpfs 8 645to confirm the file system format is FFSv2. 646. 647.It Pa /usr/mdec/bootxx_lfsv1 648Primary bootstrap for 649.Sy LFSv1 650file systems. 651. 652.It Pa /usr/mdec/bootxx_lfsv2 653Primary bootstrap for 654.Sy LFSv2 655file systems 656.Pq the default Tn LFS version . 657. 658.It Pa /usr/mdec/bootxx_msdos 659Primary bootstrap for 660.Tn MS-DOS 661.Sy FAT 662file systems. 663. 664.It Pa /usr/mdec/bootxx_ustarfs 665Primary bootstrap for 666.Sy TARFS 667boot images. 668This is used by various install media. 669. 670.It Pa /usr/mdec/boot. Ns Aq Ar MACHINE\^ 671Secondary bootstrap for machine type 672.Ar MACHINE . 673This should be installed into the file system before 674.Nm 675is run. 676. 677.It Pa /usr/mdec/boot 678Synonym for 679.Pa /usr/mdec/boot. Ns Aq Ar MACHINE\^ 680. 681.It Pa /boot. Ns Aq Ar MACHINE\^ 682Installed copy of secondary bootstrap for machine type 683.Ar MACHINE . 684. 685.It Pa /boot 686Installed copy of secondary bootstrap. 687Searched for by the primary bootstrap if 688.Pa /boot. Ns Aq Ar MACHINE\^ 689is not found. 690. 691.El 692. 693.Ss NetBSD/evbarm files 694The 695.Nx Ns /evbarm 696platform covers a wide variety of board types, many of which use \*(UB. 697Running 698.Nm 699with no options will display a list of known boards. 700Using the verbose option will also display information about which 701\*(UB package needs to be installed to support that board, 702and if the required \*(UB package is installed, 703the path at which it is located. 704.Bl -tag -width Pa 705.It Pa /usr/pkg/share/u-boot 706The default location scanned for 707\*(UB packages with installation overlays. 708.It Pa /usr/share/installboot/evbarm/boards.plist 709Base board database, used to provide information about which 710\*(UB package is required for a given board. 711.El 712. 713.Ss NetBSD/evbmips files 714. 715The 716.Nx Ns /evbmips 717bootstrap files currently only apply to the 718.Tn SBMIPS 719kernels for the 720SiByte/Broadcom 721.Tn BCM1250 722and 723.Tn BCM1480 724CPUs. 725.Bl -tag -width Pa 726. 727.It Pa /usr/mdec/sbmips/boot 728.Nx Ns /evbmips 729secondary bootstrap for FFSv1, FFSv2, LFSv1, and LFSv2. 730.It Pa /usr/mdec/sbmips/bootxx_cd9660 731.Tn SBMIPS 732primary bootstrap for ISO 9660 file system. 733.It Pa /usr/mdec/sbmips/bootxx_ffs 734.Tn SBMIPS 735primary bootstrap for FFSv1 and FFSv2 file system. 736.It Pa /usr/mdec/sbmips/bootxx_lfs 737.Tn SBMIPS 738primary bootstrap for LFSv1 and LFSv2 file system. 739.It Pa /usr/mdec/sbmips/netboot 740.Tn SBMIPS 741primary bootstrap for network root. 742.Pp 743Note that 744.Nm 745does not currently support evbmips directly. 746. 747.El 748. 749.Ss NetBSD/hppa files 750. 751.Bl -tag -width Pa 752. 753.It Pa /usr/mdec/xxboot 754.Nx Ns /hppa 755primary bootstrap for FFSv1, FFSv2, LFSv1, and LFSv2. 756.It Pa /usr/mdec/cdboot 757.Nx Ns /hppa 758primary bootstrap for ISO 9660 file system. 759.It Pa /usr/mdec/sdboot 760Synonym for 761.Pa /usr/mdec/xxboot 762. 763.El 764. 765.Ss NetBSD/macppc files 766. 767.Bl -tag -width Pa 768. 769.It Pa /usr/mdec/bootxx 770.Nx Ns /macppc 771primary bootstrap. 772. 773.It Pa /usr/mdec/ofwboot 774.Nx Ns /macppc 775secondary bootstrap. 776. 777.It Pa /ofwboot 778Installed copy of 779.Nx Ns /macppc 780secondary bootstrap. 781. 782.El 783. 784.Ss NetBSD/next68k files 785. 786.Bl -tag -width Pa 787. 788.It Pa /usr/mdec/boot 789.Nx Ns /next68k 790bootstrap. 791. 792.El 793. 794.Ss NetBSD/sparc64 files 795. 796.Bl -tag -width Pa 797. 798.It Pa /usr/mdec/bootblk 799.Nx Ns /sparc64 800primary bootstrap. 801. 802.It Pa /usr/mdec/ofwboot 803.Nx Ns /sparc64 804secondary bootstrap. 805. 806.It Pa /ofwboot 807Installed copy of 808.Nx Ns /sparc64 809secondary bootstrap. 810. 811.El 812. 813.Sh EXAMPLES 814. 815.Ss Common 816Verbosely install the Berkeley Fast File System primary bootstrap on to disk 817.Ql sd0 : 818.Pp 819.Dl installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs 820.Pp 821Note: the 822.Dq whole disk 823partition 824.Po 825.Ql c 826on some ports, 827.Ql d 828on others 829.Pc 830is used here, since the 831.Ql a 832partition 833probably is already opened 834.Po 835mounted as 836.Pa / 837.Pc , 838so 839.Nm 840would not be able to access it. 841.Pp 842Remove the primary bootstrap from disk 843.Ql sd1 : 844.Pp 845.Dl installboot -c /dev/rsd1c 846. 847.Ss NetBSD/amiga 848Modify the command line to change the default from 849.Ql "netbsd -ASn2" 850to 851.Ql "netbsd -S" : 852.Bd -literal -offset indent 853installboot -m amiga -o command="netbsd -S" /dev/rsd0a \e 854 /usr/mdec/bootxx_ffsv1 855.Ed 856. 857.Ss NetBSD/evbarm 858Install the 859\*(UB boot loader for a Pinebook into an image that will be written to 860an 861.Tn SDMMC 862card: 863.Pp 864.Dl installboot -m evbarm -o board=pine64,pinebook arm64.img 865.Pp 866Install/update the 867\*(UB boot loader for the current running system on the 868.Tn eMMC 869device 870.Ql ld0 871and display verbose information about the procedure: 872.Pp 873.Dl installboot -v /dev/rld0c 874.Pp 875Install a specific 876\*(UB package for a BeagleBone Black into an image that will be written 877to an 878.Tn SDMMC 879card: 880.Bd -literal -offset indent 881installboot -m evbarm -o board=ti,am335x-bone-black armv7.img \e 882 /path/to/experimental/u-boot/package 883.Ed 884. 885.Ss NetBSD/ews4800mips 886Install the System V Boot File System primary bootstrap on to disk 887.Ql sd0 , 888with the secondary bootstrap 889.Pa /boot 890already present in the SysVBFS partition on the disk: 891.Pp 892.Dl installboot /dev/rsd0p /usr/mdec/bootxx_bfs 893.Pp 894.Bd -ragged -offset indent-two -compact 895.Em Note : 896On 897.Nx Ns /ews4800mips 898the 899.Ql p 900partition is the 901.Dq whole disk 902.Pq i.e., raw 903partition. 904.Ed 905. 906.Ss NetBSD/i386 and NetBSD/amd64 907Install new boot blocks on an existing FFSv2 mounted root file system on 908.Ql wd0 , 909setting the timeout to five seconds, after installing an 910.Tn MBR 911bootcode and copying a new secondary bootstrap: 912.Pp 913.Dl fdisk -c /usr/mdec/mbr /dev/rwd0d 914.Pp 915.Bd -ragged -offset indent-two -compact 916.Em Note : 917See 918.Xr fdisk 8 919and 920.Xr x86/mbr 8 921for more details. 922.Ed 923.Pp 924.Dl cp /usr/mdec/boot /boot 925.Dl installboot -v -o timeout=5 /dev/rwd0a /usr/mdec/bootxx_ffsv2 926.Pp 927.Bd -ragged -offset indent-two -compact 928.Em Note : 929Pre 930.Nx 6.0 931systems used FFSv1 file systems on these platforms; double check with 932.Xr dumpfs 8 933to be sure to use the correct secondary bootstrap. 934.Ed 935.Pp 936Create a bootable 937.Tn CD-ROM 938with an ISO 9660 file system for an i386 system with a serial console: 939.Bd -literal -offset indent 940mkdir cdrom 941cp sys/arch/i386/compile/mykernel/netbsd cdrom/netbsd 942cp /usr/mdec/boot cdrom/boot 943cp /usr/mdec/bootxx_cd9660 bootxx 944installboot -o console=com0,speed=19200 -m i386 -e bootxx 945makefs -t cd9660 -o 'bootimage=i386;bootxx,no-emul-boot' boot.iso \e 946 cdrom 947.Ed 948. 949.Pp 950Create a bootable floppy disk with an FFSv1 951file system for a small custom kernel (note: bigger kernels needing 952multiple disks are handled with the ustarfs file system): 953.Pp 954.Dl newfs -s 1440k /dev/rfd0a 955.Pp 956.Bd -ragged -offset indent-two -compact 957.Em Note : 958Ignore the warnings that 959.Xr newfs 8 960displays; it can not write a disklabel, 961which is not a problem for a floppy disk. 962.Ed 963. 964.Bd -literal -offset indent 965mount /dev/fd0a /mnt 966cp /usr/mdec/boot /mnt/boot 967gzip -9 < sys/arch/i386/compile/mykernel/netbsd > /mnt/netbsd.gz 968umount /mnt 969installboot -v /dev/rfd0a /usr/mdec/bootxx_ffsv1 970.Ed 971. 972.Pp 973Create a bootable 974.Tn FAT 975file system on 976.Ql wd1a , 977which should have the same offset and size as a 978.Tn FAT 979primary partition 980in the Master Boot Record 981.Tn ( MBR ) : 982.Pp 983.Dl newfs_msdos -r 16 /dev/rwd1a 984.Pp 985.Bd -ragged -offset indent-two -compact 986.Em Notes : 987The 988.Fl r Ic 16 989is to reserve space for the primary bootstrap. 990.Xr newfs_msdos 8 991will display an 992.Dq Tn MBR type 993such as 994.Ql 1 , 995.Ql 4 , 996or 997.Ql 6 ; 998the 999.Tn MBR 1000partition type of the appropriate primary partition should be 1001changed to this value. 1002.Ed 1003. 1004.Bd -literal -offset indent 1005mount -t msdos /dev/wd1a /mnt 1006cp /usr/mdec/boot /mnt/boot 1007cp path/to/kernel /mnt/netbsd 1008umount /mnt 1009installboot -t raw /dev/rwd1a /usr/mdec/bootxx_msdos 1010.Ed 1011.Pp 1012Make the existing 1013.Tn FAT16 1014filesystem on 1015.Ql sd0e 1016bootable. 1017This can be used to make 1018.Tn USB 1019memory bootable provided it has 512 byte 1020sectors and that the manufacturer correctly initialised the file system. 1021.Bd -literal -offset indent 1022mount -t msdos /dev/sd0e /mnt 1023cp /usr/mdec/boot /mnt/boot 1024cp path/to/kernel /mnt/netbsd 1025umount /mnt 1026installboot /dev/rsd0e /usr/mdec/bootxx_fat16 1027.Ed 1028.Pp 1029It may also be necessary to use 1030.Xr fdisk 8 1031to make the device itself bootable. 1032. 1033.Pp 1034Switch the existing installed bootstrap to use a serial console without 1035reinstalling or altering other options such as timeout. 1036.Pp 1037.Dl installboot -e -o console=com0 /dev/rwd0a 1038. 1039.Ss NetBSD/macppc 1040Note the 1041.Nm 1042utility is only required for macppc machines with OpenFirmware version 2 1043to boot. 1044OpenFirmware 3 cannot load bootblocks specified in the Apple partition 1045map. 1046.Pp 1047Install the Berkeley Fast File System primary bootstrap on to disk 1048.Ql wd0 : 1049.Pp 1050.Dl installboot /dev/rwd0c /usr/mdec/bootxx /ofwboot 1051.Pp 1052The secondary 1053.Nx Ns /macppc 1054bootstrap is located in 1055.Pa /usr/mdec/ofwboot . 1056.Pp 1057The primary bootstrap requires the raw 1058.Pa ofwboot 1059for the secondary bootstrap, not 1060.Pa ofwboot.xcf , 1061which is used for the OpenFirmware to load kernels. 1062. 1063.Ss NetBSD/next68k 1064Install the bootstrap on to disk 1065.Ql sd0 : 1066.Pp 1067.Dl installboot /dev/rsd0c /usr/mdec/boot 1068. 1069.Ss NetBSD/pmax 1070Install the Berkeley Fast File System primary bootstrap on to disk 1071.Ql sd0 : 1072.Pp 1073.Dl installboot /dev/rsd0c /usr/mdec/bootxx_ffs 1074.Pp 1075.Nx Ns /pmax 1076requires that this file system starts at block 0 of the disk. 1077.Pp 1078Install the ISO 9660 primary bootstrap in the file 1079.Pa /tmp/cd-image : 1080.Pp 1081.Dl installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 1082.Pp 1083Make an ISO 9660 filesystem in the file 1084.Pa /tmp/cd-image 1085and install the ISO 9660 primary bootstrap in the filesystem, where the 1086source directory for the ISO 9660 filesystem contains a kernel, the 1087primary bootstrap 1088.Pa bootxx_cd9660 1089and the secondary bootstrap 1090.Pa boot.pmax : 1091.Bd -literal -offset indent 1092mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 1093\&... 109448 51 iso-source-dir/bootxx_cd9660 1095\&... 1096installboot -b $((48 * 4)) /tmp/cd-image /usr/mdec/bootxx_cd9660 1097.Ed 1098. 1099.Ss NetBSD/sparc 1100Install the Berkeley Fast File System primary bootstrap on to disk 1101.Ql sd0 , 1102with the secondary bootstrap 1103.Pa /boot 1104already present: 1105.Pp 1106.Dl installboot /dev/rsd0c /usr/mdec/bootxx /boot 1107. 1108.Ss NetBSD/sparc64 1109Install the primary bootstrap on to disk 1110.Ql sd0 : 1111.Pp 1112.Dl installboot /dev/rsd0c /usr/mdec/bootblk 1113.Pp 1114The secondary 1115.Nx Ns /sparc64 1116bootstrap is located in 1117.Pa /usr/mdec/ofwboot . 1118. 1119.Ss NetBSD/sun2 and NetBSD/sun3 1120Install the Berkeley Fast File System primary bootstrap on to disk 1121.Ql sd0 , 1122with the secondary bootstrap 1123.Pa /boot 1124already present: 1125.Pp 1126.Dl installboot /dev/rsd0c /usr/mdec/bootxx /boot 1127. 1128.Ss NetBSD/vax 1129Install the Berkeley Fast File System primary bootstrap on to disk 1130.Ql ra0 : 1131.Pp 1132.Dl installboot /dev/rra0c /usr/mdec/raboot 1133.Pp 1134The primary bootstrap works with FFSv1 and FFSv2 file systems. 1135The secondary 1136.Nx Ns /vax 1137bootstrap is located in 1138.Pa /usr/mdec/boot . 1139. 1140.Sh DIAGNOSTIC 1141.Ex -std 1142. 1143.Sh SEE ALSO 1144.Xr uname 3 , 1145.Xr boot 8 , 1146.Xr disklabel 8 , 1147.Xr dumpfs 8 , 1148.Xr fdisk 8 , 1149.Xr gpt 8 , 1150.Xr x86/mbr 8 , 1151.Xr x86/pxeboot 8 1152. 1153.Sh HISTORY 1154This implementation of 1155.Nm 1156appeared in 1157.Nx 1.6 . 1158. 1159.Sh AUTHORS 1160.An -nosplit 1161The machine independent portion of this implementation of 1162.Nm 1163was written by 1164.An Luke Mewburn . 1165The following people contributed to the various machine dependent 1166back-ends: 1167.An Simon Burge 1168(pmax), 1169.An Chris Demetriou 1170(alpha), 1171.An Matthew Fredette 1172(sun2, sun3), 1173.An Matthew Green 1174(sparc64), 1175.An Ross Harvey 1176(alpha), 1177.An Michael Hitch 1178(amiga), 1179.An Paul Kranenburg 1180(sparc), 1181.An David Laight 1182(i386), 1183.An Christian Limpach 1184(next68k), 1185.An Luke Mewburn 1186(macppc), 1187.An Matt Thomas 1188(vax), 1189.An Izumi Tsutsui 1190(news68k, newsmips), 1191and 1192.An UCHIYAMA Yasushi 1193(ews4800mips). 1194. 1195.Sh BUGS 1196There are not currently primary bootstraps to support all file systems 1197types which are capable of being the root file system. 1198.Pp 1199If a disk has been converted from 1200.Tn FFS 1201to 1202.Tn RAID 1203without the contents of the disk erased, then the original 1204.Tn FFS 1205installation may be auto-detected instead of the 1206.Tn RAID 1207installation. 1208In this case, the 1209.Fl t Ic raid 1210option must be provided. 1211. 1212.Ss NetBSD/alpha 1213The 1214.Nx Ns /alpha 1215primary bootstrap program can only load the secondary bootstrap program 1216from file systems starting at the beginning 1217.Pq block 0 1218of disks. 1219Similarly, the secondary bootstrap program can only load kernels from 1220file systems starting at the beginning of disks. 1221.Pp 1222The size of primary bootstrap programs is restricted to 7.5KB, even 1223though some file systems 1224.Pq e.g., ISO 9660 1225are able to accommodate larger ones. 1226. 1227.Ss NetBSD/hp300 1228The disk must have a boot partition large enough to hold the bootstrap code. 1229Currently the primary bootstrap must be a LIF format file. 1230. 1231.Ss NetBSD/i386 and NetBSD/amd64 1232The bootstrap must be installed in the 1233.Nx 1234partition that starts at the beginning of the 1235.Tn MBR 1236partition. 1237If that is a valid filesystem and contains the 1238.Pa /boot 1239program then it will be used as the root filesystem, otherwise the 1240.Ql a 1241partition will be booted. 1242.Pp 1243The size of primary bootstrap programs is restricted to 8KB, even 1244though some file systems 1245.Pq e.g., ISO 9660 1246are able to accommodate larger ones. 1247. 1248.Ss NetBSD/macppc 1249Due to restrictions in 1250.Nm 1251and the secondary bootstrap implementation, file systems where kernels exist 1252must start at the beginning of disks. 1253.Pp 1254Currently, 1255.Nm 1256doesn't recognize an existing Apple partition map on the disk 1257and always writes a faked map to make disks bootable. 1258.Pp 1259The 1260.Nx Ns /macppc 1261bootstrap program can't load kernels from FFSv2 partitions. 1262. 1263.Ss NetBSD/next68k 1264The size of bootstrap programs is restricted to the free space before 1265the file system at the beginning of the disk minus 8KB. 1266. 1267.Ss NetBSD/pmax 1268The 1269.Nx Ns /pmax 1270secondary bootstrap program can only load kernels from file 1271systems starting at the beginning of disks. 1272.Pp 1273The size of primary bootstrap programs is restricted to 7.5KB, even 1274though some file systems 1275.Pq e.g., ISO 9660 1276are able to accommodate larger ones. 1277. 1278.Ss NetBSD/sun2 and NetBSD/sun3 1279The 1280.Nx Ns /sun2 1281and 1282.Nx Ns /sun3 1283secondary bootstrap program can only load kernels from file 1284systems starting at the beginning of disks. 1285. 1286.Ss NetBSD/vax 1287The 1288.Nx Ns /vax 1289secondary bootstrap program can only load kernels from file systems 1290starting at the beginning of disks. 1291.Pp 1292The size of primary bootstrap programs is restricted to 7.5KB, even 1293though some file systems 1294.Pq e.g., ISO 9660 1295are able to accommodate larger ones. 1296