1.\" $NetBSD: installboot.8,v 1.28 2003/04/20 00:38:31 lukem 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/pmax 430Install the Berkeley Fast File System primary bootstrap on to disk 431.Sq sd0 : 432.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 433.Pp 434.Nx Ns Tn /pmax 435requires that this file system starts at block 0 of the disk. 436.Pp 437Install the ISO 9660 primary bootstrap in the file 438.Pa /tmp/cd-image : 439.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 440.Pp 441Make an ISO 9660 filesystem in the file 442.Pa /tmp/cd-image 443and install the ISO 9660 primary bootstrap in the filesystem, where the 444source directory for the ISO 9660 filesystem contains a kernel, the 445primary bootstrap 446.Pp 447.Pa bootxx_cd9660 448and the secondary bootstrap 449.Pa boot.pmax : 450.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 451.Dl ... 452.Dl 48 51 iso-source-dir/bootxx_cd9660 453.Dl ... 454.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 455. 456.Ss NetBSD/sparc 457Install the Berkeley Fast File System primary bootstrap on to disk 458.Sq sd0 , 459with the secondary bootstrap 460.Sq Pa /boot 461already present: 462.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 463. 464.Ss NetBSD/sparc64 465Install the Berkeley Fast File System primary bootstrap on to disk 466.Sq wd0 : 467.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk 468.Pp 469The secondary 470.Nx Ns Tn /sparc64 471bootstrap is located in 472.Pa /usr/mdec/ofwboot . 473. 474.Ss NetBSD/sun2 and NetBSD/sun3 475Install the Berkeley Fast File System primary bootstrap on to disk 476.Sq sd0 , 477with the secondary bootstrap 478.Sq Pa /boot 479already present: 480.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 481. 482.Ss NetBSD/amiga examples 483Modify the command line to change the default from "netbsd -ASn2" to 484"netbsd -S": 485.Dl Ic installboot -m amiga -o command="netbsd -S" /dev/rsd0a /usr/mdec/bootxx_ffs 486. 487.Sh SEE ALSO 488.Xr uname 3 , 489.Xr boot 8 , 490.Xr disklabel 8 491. 492.Sh HISTORY 493This implementation of 494.Nm 495appeared in 496.Nx 1.6 . 497. 498.Sh AUTHORS 499The machine independent portion of this implementation of 500.Nm 501was written by Luke Mewburn. 502The following people contributed to the various machine dependent 503back-ends: 504Simon Burge (pmax), 505Chris Demetriou (alpha), 506Matthew Fredette (sun2, sun3), 507Matthew Green (sparc64), 508Ross Harvey (alpha), 509Michael Hitch (amiga), 510Paul Kranenburg (sparc), 511David Laight (i386), 512Luke Mewburn (macppc), 513Matt Thomas (vax), 514and 515Izumi Tsutsui (news68k, newsmips). 516. 517.Sh BUGS 518There are not currently primary bootstraps to support all file systems 519types which are capable of being the root file system. 520. 521.Ss NetBSD/alpha 522The 523.Nx Ns Tn /alpha 524primary bootstrap program can only load the secondary bootstrap program 525from file systems starting at the beginning (block 0) of disks. 526Similarly, the secondary bootstrap program can only load kernels from 527file systems starting at the beginning of disks. 528.Pp 529The size of primary bootstrap programs is restricted to 7.5KB, even 530though some file systems (e.g., ISO 9660) are able to accommodate larger 531ones. 532. 533.Ss NetBSD/i386 534The size of primary bootstrap programs is restricted to 8KB, even 535though some file systems (e.g., ISO 9660) are able to accommodate larger 536ones. 537. 538.Ss NetBSD/pmax 539The 540.Nx Ns Tn /pmax 541secondary bootstrap program can only load kernels from file 542systems starting at the beginning of disks. 543.Pp 544The size of primary bootstrap programs is restricted to 7.5KB, even 545though some file systems (e.g., ISO 9660) are able to accommodate larger 546ones. 547. 548.Ss NetBSD/sun2 and NetBSD/sun3 549The 550.Nx Ns Tn /sun2 551and 552.Nx Ns Tn /sun3 553secondary bootstrap program can only load kernels from file 554systems starting at the beginning of disks. 555. 556.Ss NetBSD/vax 557The 558.Nx Ns Tn /vax 559secondary bootstrap program can only load kernels from file systems 560starting at the beginning of disks. 561.Pp 562The size of primary bootstrap programs is restricted to 7.5KB, even 563though some file systems (e.g., ISO 9660) are able to accommodate larger 564ones. 565