1.\" $NetBSD: installboot.8,v 1.23 2002/10/03 07:27:50 lukem Exp $ 2.\" 3.\" Copyright (c) 2002 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 October 3, 2002 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 111Some platform 112.Pq Fl m Ar machine 113and file system type 114.Pq Fl t Ar fstype 115combinations require that the name of the secondary bootstrap is 116supplied as 117.Ar secondary , 118so that information such as the disk block numbers occupied 119by the secondary bootstrap can be stored in the primary bootstrap. 120These are: 121.Bl -column "Platform" "File systems" -offset indent 122.It Sy "Platform" Ta Sy "File systems" 123.It macppc Ta ffs, raw 124.It news68k Ta ffs, raw 125.It newsmips Ta ffs, raw 126.It sparc Ta ffs, raw 127.It sun2 Ta ffs, raw 128.It sun3 Ta ffs, raw 129.El 130.Pp 131Perform the following steps to make a file system bootable: 132.Bl -enum 133.It 134Copy the secondary bootstrap (usually 135.Pa /usr/mdec/boot. Ns Sy MACHINE 136or 137.Pa /usr/mdec/boot ) 138to the root directory of the target file system. 139.Pp 140. 141.It 142Use 143.Nm 144to install the primary bootstrap program 145(usually 146.Pa /usr/mdec/bootxx_ Ns Sy FSTYPE ) 147into 148.Ar filesystem . 149.Pp 150The following platforms do not require this step if the primary bootstrap 151already exists and the secondary bootstrap file is just being updated: 152.Sy alpha , 153.Sy pmax , 154.Sy sparc64 , 155and 156.Sy vax . 157.Pp 158.El 159.Pp 160The options recognized by 161.Nm 162are as follows: 163. 164.Bl -tag -width "optionsxxx" 165. 166.It Fl b Ar s1bno 167Install 168.Ar primary 169at block number 170.Ar s1bno 171instead of the default location for the machine and file system type. 172.Sy [ alpha , 173.Sy pmax , 174.Sy vax ] 175. 176.It Fl B Ar s2bno 177When hard-coding the blocks of 178.Ar secondary 179into 180.Ar primary , 181start from block 182.Ar s2bno 183instead of trying to determine the block numbers occupied by 184.Ar secondary 185by examining 186.Ar filesystem . 187If this option is supplied, 188.Ar secondary 189should refer to an actual secondary bootstrap (rather than the 190file name of the one present in 191.Ar filesystem ) 192so that its size can be determined. 193. 194.It Fl c 195Clear (remove) any existing bootstrap instead of installing one. 196. 197.It Fl m Ar machine 198Use 199.Ar machine 200as the target machine type. 201The default machine is determined from 202.Xr uname 3 203and then 204.Ev MACHINE . 205The following machines are currently supported by 206.Nm "" : 207.Bd -ragged -offset indent 208.Sy alpha , 209.Sy macppc , 210.Sy news68k , 211.Sy newsmips , 212.Sy pmax , 213.Sy sparc , 214.Sy sparc64 , 215.Sy sun2 , 216.Sy sun3 , 217.Sy vax , 218.Sy x68k 219.Ed 220. 221. 222.It Fl n 223Do not write to 224.Ar filesystem . 225. 226.It Fl o Ar options 227Machine specific 228.Nm 229options, comma separated. 230.Pp 231Supported options are (with the machines for they are valid in brackets): 232. 233.Bl -tag -offset indent -width alphasum 234. 235.It Sy alphasum 236.Sy [ alpha ] 237Recalculate and restore the Alpha checksum. 238This is the default for 239.Nx Ns Tn /alpha . 240. 241.It Sy append 242.Sy [ alpha , 243.Sy pmax , 244.Sy vax ] 245Append 246.Ar primary 247to the end of 248.Ar filesystem , 249which must be a regular file in this case. 250. 251.It Sy sunsum 252.Sy [ alpha , 253.Sy pmax , 254.Sy vax ] 255Recalculate and restore the Sun and 256.Nx Ns Tn /sparc 257compatible checksum. 258.Em Note : 259The existing 260.Nx Ns Tn /sparc 261disklabel should use no more than 4 partitions. 262.El 263. 264.It Fl t Ar fstype 265Use 266.Ar fstype 267as the type of 268.Ar filesystem . 269The default operation is to attempt to auto-detect this setting. 270The following file system types are currently supported by 271.Nm "" : 272. 273.Bl -tag -offset indent -width ffs 274. 275.It Sy ffs 276.Bx 277Fast File System. 278. 279.It Sy raw 280.Sq Raw 281image. 282Note: if a platform needs to hard-code the block offset of the secondary 283bootstrap, it cannot be searched for on this file system type, and must 284be provided with 285.Fl B Ar s2bno . 286.El 287. 288.It Fl v 289Verbose operation. 290.El 291.Pp 292.Nm 293exits 0 on success, and \*[Gt]0 if an error occurs. 294. 295.Sh ENVIRONMENT 296.Nm 297uses the following environment variables: 298. 299.Bl -tag -width "MACHINE" 300. 301.It Ev MACHINE 302Default value for 303.Ar machine , 304overriding the result from 305.Xr uname 3 . 306. 307.El 308. 309.Sh FILES 310Most 311.Nx 312ports will contain variations of the following files: 313.Pp 314.Bl -tag -width /usr/mdec/boot.$MACHINE 315. 316.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE 317Primary bootstrap for file system type 318.Sy FSTYPE . 319Installed into the bootstrap area of the file system by 320.Nm "" . 321. 322.It Pa /usr/mdec/boot. Ns Sy MACHINE 323Secondary bootstrap for machine type 324.Sy MACHINE . 325This should be installed into the file system before 326.Nm 327is run. 328. 329.It Pa /boot. Ns Sy MACHINE 330Installed copy of secondary bootstrap for machine type 331.Sy MACHINE . 332. 333.It Pa /boot 334Installed copy of secondary bootstrap. 335Searched for by the primary bootstrap if 336.Pa /boot. Ns Sy MACHINE 337is not found. 338. 339.El 340. 341.Ss NetBSD/sparc64 files 342. 343.Bl -tag -width /usr/mdec/boot.$MACHINE 344. 345.It Pa /usr/mdec/bootblk 346.Nx Ns Tn /sparc64 347primary bootstrap. 348. 349.It Pa /usr/mdec/ofwboot 350.Nx Ns Tn /sparc64 351secondary bootstrap. 352. 353.It Pa /ofwboot 354Installed copy of 355.Nx Ns Tn /sparc64 356secondary bootstrap. 357. 358.El 359. 360.Sh EXAMPLES 361. 362.Ss common 363Verbosely install the Berkeley Fast File System primary bootstrap on to disk 364.Sq sd0 : 365.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs 366.Pp 367Remove the primary bootstrap from disk 368.Sq sd1 : 369.Dl Ic installboot -c /dev/rsd1c 370. 371.Ss NetBSD/pmax 372Install the Berkeley Fast File System primary bootstrap on to disk 373.Sq sd0 : 374.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 375.Pp 376.Nx Ns Tn /pmax 377requires that this file system starts at block 0 of the disk. 378.Pp 379Install the ISO 9660 primary bootstrap in the file 380.Pa /tmp/cd-image : 381.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 382.Pp 383Make an ISO 9660 filesystem in the file 384.Pa /tmp/cd-image 385and install the ISO 9660 primary bootstrap in the filesystem, where the 386source directory for the ISO 9660 filesystem contains a kernel, the 387primary bootstrap 388.Pp 389.Pa bootxx_cd9660 390and the secondary bootstrap 391.Pa boot.pmax : 392.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 393.Dl ... 394.Dl 48 51 iso-source-dir/bootxx_cd9660 395.Dl ... 396.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 397. 398.Ss NetBSD/sparc 399Install the Berkeley Fast File System primary bootstrap on to disk 400.Sq sd0 , 401with the secondary bootstrap 402.Sq Pa /boot 403already present: 404.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 405. 406.Ss NetBSD/sparc64 407Install the Berkeley Fast File System primary bootstrap on to disk 408.Sq wd0 : 409.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk 410.Pp 411The secondary 412.Nx Ns Tn /sparc64 413bootstrap is located in 414.Pa /usr/mdec/ofwboot . 415. 416.Ss NetBSD/sun2 and NetBSD/sun3 417Install the Berkeley Fast File System primary bootstrap on to disk 418.Sq sd0 , 419with the secondary bootstrap 420.Sq Pa /boot 421already present: 422.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 423. 424.Sh SEE ALSO 425.Xr uname 3 , 426.Xr boot 8 , 427.Xr disklabel 8 428. 429.Sh HISTORY 430This implementation of 431.Nm 432appeared in 433.Nx 1.6 . 434. 435.Sh AUTHORS 436The machine independent portion of this implementation of 437.Nm 438was written by Luke Mewburn. 439The following people contributed to the various machine dependent 440back-ends: 441Simon Burge (pmax), 442Chris Demetriou (alpha), 443Matthew Fredette (sun2, sun3), 444Matthew Green (sparc64), 445Ross Harvey (alpha), 446Paul Kranenburg (sparc), 447Luke Mewburn (macppc), 448Matt Thomas (vax), 449and 450Izumi Tsutsui (news68k, newsmips). 451. 452.Sh BUGS 453There are not currently primary bootstraps to support all file systems 454types which are capable of being the root file system. 455. 456.Ss NetBSD/alpha 457The 458.Nx Ns Tn /alpha 459primary bootstrap program can only load the secondary bootstrap program 460from file systems starting at the beginning (block 0) of disks. 461Similarly, the secondary bootstrap program can only load kernels from 462file systems starting at the beginning of disks. 463.Pp 464The size of primary bootstrap programs is restricted to 7.5KB, even 465though some file systems (e.g. ISO 9660) are able to accommodate larger 466ones. 467. 468.Ss NetBSD/pmax 469The 470.Nx Ns Tn /pmax 471secondary bootstrap program can only load kernels from file 472systems starting at the beginning of disks. 473.Pp 474The size of primary bootstrap programs is restricted to 7.5KB, even 475though some file systems (e.g. ISO 9660) are able to accommodate larger 476ones. 477. 478.Ss NetBSD/sun2 and NetBSD/sun3 479The 480.Nx Ns Tn /sun2 481and 482.Nx Ns Tn /sun3 483secondary bootstrap program can only load kernels from file 484systems starting at the beginning of disks. 485. 486.Ss NetBSD/vax 487The 488.Nx Ns Tn /vax 489secondary bootstrap program can only load kernels from file systems 490starting at the beginning of disks. 491.Pp 492The size of primary bootstrap programs is restricted to 7.5KB, even 493though some file systems (e.g. ISO 9660) are able to accommodate larger 494ones. 495