1.\" $NetBSD: installboot.8,v 1.29 2003/08/16 18:42:53 martin 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 April 20, 2003 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 amiga , 134.Sy i386 , 135.Sy pmax , 136.Sy sparc64 , 137and 138.Sy vax . 139.Pp 140.El 141.Pp 142The options and arguments recognized by 143.Nm 144are as follows: 145. 146.Bl -tag -width "optionsxxx" 147. 148.It Fl b Ar s1bno 149Install 150.Ar primary 151at block number 152.Ar s1bno 153instead of the default location for the machine and file system type. 154.Sy [ alpha , 155.Sy pmax , 156.Sy vax ] 157. 158.It Fl B Ar s2bno 159When hard-coding the blocks of 160.Ar secondary 161into 162.Ar primary , 163start from block 164.Ar s2bno 165instead of trying to determine the block numbers occupied by 166.Ar secondary 167by examining 168.Ar filesystem . 169If this option is supplied, 170.Ar secondary 171should refer to an actual secondary bootstrap (rather than the 172file name of the one present in 173.Ar filesystem ) 174so that its size can be determined. 175. 176.It Fl c 177Clear (remove) any existing bootstrap instead of installing one. 178. 179.It Fl m Ar machine 180Use 181.Ar machine 182as the target machine type. 183The default machine is determined from 184.Xr uname 3 185and then 186.Ev MACHINE . 187The following machines are currently supported by 188.Nm : 189.Bd -ragged -offset indent 190.Sy alpha , 191.Sy amiga , 192.Sy i386 , 193.Sy macppc , 194.Sy news68k , 195.Sy newsmips , 196.Sy pmax , 197.Sy sparc , 198.Sy sparc64 , 199.Sy sun2 , 200.Sy sun3 , 201.Sy vax , 202.Sy x68k 203.Ed 204. 205. 206.It Fl n 207Do not write to 208.Ar filesystem . 209. 210.It Fl o Ar options 211Machine specific 212.Nm 213options, comma separated. 214.Pp 215Supported options are (with the machines for they are valid in brackets): 216. 217.Bl -tag -offset indent -width alphasum 218. 219.It Sy alphasum 220.Sy [ alpha ] 221Recalculate and restore the Alpha checksum. 222This is the default for 223.Nx Ns Tn /alpha . 224. 225.It Sy append 226.Sy [ alpha , 227.Sy pmax , 228.Sy vax ] 229Append 230.Ar primary 231to the end of 232.Ar filesystem , 233which must be a regular file in this case. 234. 235.It Sy command=<boot command> 236.Sy [ amiga ] 237Modify the default boot command line. 238. 239.It Sy console=<console name> 240.Sy [ i386 ] 241Set the console device, <console name> must be one of: 242pc, com0, com1, com2, com3, com0kbd, com1kbd, com2kbd or com3kbd. 243. 244.It Sy password=<password> 245.Sy [ i386 ] 246Set the password which must be entered before the boot menu can be accessed. 247. 248.It Sy resetvideo 249.Sy [ i386 ] 250Reset the video before booting. 251. 252.It Sy speed=<baud rate> 253.Sy [ i386 ] 254Set the baud rate for the serial console. 255. 256.It Sy sunsum 257.Sy [ alpha , 258.Sy pmax , 259.Sy vax ] 260Recalculate and restore the Sun and 261.Nx Ns Tn /sparc 262compatible checksum. 263.Em Note : 264The existing 265.Nx Ns Tn /sparc 266disklabel should use no more than 4 partitions. 267. 268.It Sy timeout=<seconds> 269.Sy [ i386 ] 270Set the timeout before the automatic boot begins to the given number of seconds. 271.El 272. 273.It Fl t Ar fstype 274Use 275.Ar fstype 276as the type of 277.Ar filesystem . 278The default operation is to attempt to auto-detect this setting. 279The following file system types are currently supported by 280.Nm : 281. 282.Bl -tag -offset indent -width ffs 283. 284.It Sy ffs 285.Bx 286Fast File System. 287. 288.It Sy raw 289.Sq Raw 290image. 291Note: if a platform needs to hard-code the block offset of the secondary 292bootstrap, it cannot be searched for on this file system type, and must 293be provided with 294.Fl B Ar s2bno . 295.El 296. 297.It Fl v 298Verbose operation. 299. 300.It Ar filesystem 301The path name of the device or file system image that 302.Nm 303is to operate on. 304It is not necessary for 305.Ar filesystem 306to be a currently mounted file system. 307. 308.It Ar primary 309The path name of the 310.Dq primary 311boot block to install. 312. 313.It Ar secondary 314The path name of the 315.Dq secondary 316boot block, 317relative to the top of 318.Ar filesystem . 319Most systems require 320.Ar secondary 321to be in the 322.Dq root 323directory of the file system, so the leading 324.Dq Pa / 325is not necessary on 326.Ar secondary . 327.Pp 328Only certain combinations of 329platform 330.Pq Fl m Ar machine 331and file system type 332.Pq Fl t Ar fstype 333require that the name of the secondary bootstrap is 334supplied as 335.Ar secondary , 336so that information such as the disk block numbers occupied 337by the secondary bootstrap can be stored in the primary bootstrap. 338These are: 339.Bl -column "Platform" "File systems" -offset indent 340.It Sy "Platform" Ta Sy "File systems" 341.It macppc Ta ffs, raw 342.It news68k Ta ffs, raw 343.It newsmips Ta ffs, raw 344.It sparc Ta ffs, raw 345.It sun2 Ta ffs, raw 346.It sun3 Ta ffs, raw 347.El 348.El 349.Pp 350.Nm 351exits 0 on success, and \*[Gt]0 if an error occurs. 352. 353.Sh ENVIRONMENT 354.Nm 355uses the following environment variables: 356. 357.Bl -tag -width "MACHINE" 358. 359.It Ev MACHINE 360Default value for 361.Ar machine , 362overriding the result from 363.Xr uname 3 . 364. 365.El 366. 367.Sh FILES 368Most 369.Nx 370ports will contain variations of the following files: 371.Pp 372.Bl -tag -width /usr/mdec/boot.$MACHINE 373. 374.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE 375Primary bootstrap for file system type 376.Sy FSTYPE . 377Installed into the bootstrap area of the file system by 378.Nm . 379. 380.It Pa /usr/mdec/boot. Ns Sy MACHINE 381Secondary bootstrap for machine type 382.Sy MACHINE . 383This should be installed into the file system before 384.Nm 385is run. 386. 387.It Pa /boot. Ns Sy MACHINE 388Installed copy of secondary bootstrap for machine type 389.Sy MACHINE . 390. 391.It Pa /boot 392Installed copy of secondary bootstrap. 393Searched for by the primary bootstrap if 394.Pa /boot. Ns Sy MACHINE 395is not found. 396. 397.El 398. 399.Ss NetBSD/sparc64 files 400. 401.Bl -tag -width /usr/mdec/boot.$MACHINE 402. 403.It Pa /usr/mdec/bootblk 404.Nx Ns Tn /sparc64 405primary bootstrap. 406. 407.It Pa /usr/mdec/ofwboot 408.Nx Ns Tn /sparc64 409secondary bootstrap. 410. 411.It Pa /ofwboot 412Installed copy of 413.Nx Ns Tn /sparc64 414secondary bootstrap. 415. 416.El 417. 418.Sh EXAMPLES 419. 420.Ss common 421Verbosely install the Berkeley Fast File System primary bootstrap on to disk 422.Sq sd0 : 423.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs 424.Pp 425Remove the primary bootstrap from disk 426.Sq sd1 : 427.Dl Ic installboot -c /dev/rsd1c 428. 429.Ss NetBSD/i386 430Create a bootable floppy disk with UFS file system for a small custom 431kernel (note: bigger kernels needing multiple disks are handled with 432the ustarfs file system): 433.Dl Ic newfs -s 1440k /dev/rfd0a 434Ignore the warnings this spews (it can not write a disklabel, which is no 435problem for a floppy disk) 436.Dl Ic mount /dev/fd0a /mnt 437.Dl Ic cp /usr/mdec/biosboot /mnt/boot 438.Dl Ic gzip -9 < sys/arch/i386/compile/mykernel/netbsd > /mnt/netbsd.gz 439.Dl Ic umount /mnt 440.Dl Ic installboot -v /dev/rfd0a /usr/mdec/bootxx_ufs 441.Ss NetBSD/pmax 442Install the Berkeley Fast File System primary bootstrap on to disk 443.Sq sd0 : 444.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 445.Pp 446.Nx Ns Tn /pmax 447requires that this file system starts at block 0 of the disk. 448.Pp 449Install the ISO 9660 primary bootstrap in the file 450.Pa /tmp/cd-image : 451.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 452.Pp 453Make an ISO 9660 filesystem in the file 454.Pa /tmp/cd-image 455and install the ISO 9660 primary bootstrap in the filesystem, where the 456source directory for the ISO 9660 filesystem contains a kernel, the 457primary bootstrap 458.Pp 459.Pa bootxx_cd9660 460and the secondary bootstrap 461.Pa boot.pmax : 462.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 463.Dl ... 464.Dl 48 51 iso-source-dir/bootxx_cd9660 465.Dl ... 466.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 467. 468.Ss NetBSD/sparc 469Install the Berkeley Fast File System primary bootstrap on to disk 470.Sq sd0 , 471with the secondary bootstrap 472.Sq Pa /boot 473already present: 474.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 475. 476.Ss NetBSD/sparc64 477Install the Berkeley Fast File System primary bootstrap on to disk 478.Sq wd0 : 479.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk 480.Pp 481The secondary 482.Nx Ns Tn /sparc64 483bootstrap is located in 484.Pa /usr/mdec/ofwboot . 485. 486.Ss NetBSD/sun2 and NetBSD/sun3 487Install the Berkeley Fast File System primary bootstrap on to disk 488.Sq sd0 , 489with the secondary bootstrap 490.Sq Pa /boot 491already present: 492.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 493. 494.Ss NetBSD/amiga examples 495Modify the command line to change the default from "netbsd -ASn2" to 496"netbsd -S": 497.Dl Ic installboot -m amiga -o command="netbsd -S" /dev/rsd0a /usr/mdec/bootxx_ffs 498. 499.Sh SEE ALSO 500.Xr uname 3 , 501.Xr boot 8 , 502.Xr disklabel 8 503. 504.Sh HISTORY 505This implementation of 506.Nm 507appeared in 508.Nx 1.6 . 509. 510.Sh AUTHORS 511The machine independent portion of this implementation of 512.Nm 513was written by Luke Mewburn. 514The following people contributed to the various machine dependent 515back-ends: 516Simon Burge (pmax), 517Chris Demetriou (alpha), 518Matthew Fredette (sun2, sun3), 519Matthew Green (sparc64), 520Ross Harvey (alpha), 521Michael Hitch (amiga), 522Paul Kranenburg (sparc), 523David Laight (i386), 524Luke Mewburn (macppc), 525Matt Thomas (vax), 526and 527Izumi Tsutsui (news68k, newsmips). 528. 529.Sh BUGS 530There are not currently primary bootstraps to support all file systems 531types which are capable of being the root file system. 532. 533.Ss NetBSD/alpha 534The 535.Nx Ns Tn /alpha 536primary bootstrap program can only load the secondary bootstrap program 537from file systems starting at the beginning (block 0) of disks. 538Similarly, the secondary bootstrap program can only load kernels from 539file systems starting at the beginning of disks. 540.Pp 541The size of primary bootstrap programs is restricted to 7.5KB, even 542though some file systems (e.g., ISO 9660) are able to accommodate larger 543ones. 544. 545.Ss NetBSD/i386 546The size of primary bootstrap programs is restricted to 8KB, even 547though some file systems (e.g., ISO 9660) are able to accommodate larger 548ones. 549. 550.Ss NetBSD/pmax 551The 552.Nx Ns Tn /pmax 553secondary bootstrap program can only load kernels from file 554systems starting at the beginning of disks. 555.Pp 556The size of primary bootstrap programs is restricted to 7.5KB, even 557though some file systems (e.g., ISO 9660) are able to accommodate larger 558ones. 559. 560.Ss NetBSD/sun2 and NetBSD/sun3 561The 562.Nx Ns Tn /sun2 563and 564.Nx Ns Tn /sun3 565secondary bootstrap program can only load kernels from file 566systems starting at the beginning of disks. 567. 568.Ss NetBSD/vax 569The 570.Nx Ns Tn /vax 571secondary bootstrap program can only load kernels from file systems 572starting at the beginning of disks. 573.Pp 574The size of primary bootstrap programs is restricted to 7.5KB, even 575though some file systems (e.g., ISO 9660) are able to accommodate larger 576ones. 577