1.\" $NetBSD: installboot.8,v 1.13 2002/05/06 23:18:20 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 May 7, 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 bno 58.Ek 59.Ar filesystem 60.Ar primary 61.Op Ar secondary 62.Nm "" 63.Fl c 64.Op Fl nv 65.Bk -words 66.Op Fl m Ar machine 67.Ek 68.Bk -words 69.Op Fl o Ar options 70.Ek 71.Bk -words 72.Op Fl t Ar fstype 73.Ek 74.Ar filesystem 75. 76.Sh DESCRIPTION 77The 78.Nm 79utility installs and removes 80.Nx 81disk bootstrap software into a file system. 82.Nm 83can install 84.Ar primary 85into 86.Ar filesystem , 87or disable an existing bootstrap in 88.Ar filesystem . 89.Pp 90Generally, 91.Nx 92disk bootstrap software consists of two parts: a 93.Dq primary 94bootstrap program usually written into the disklabel area of the 95file system by 96.Nm "" , 97and a 98.Dq secondary 99bootstrap program that usually resides as an ordinary file in the file system. 100.Pp 101When booting, the primary bootstrap program is loaded and invoked by 102the machine's PROM or BIOS. 103After receiving control of the system it loads and runs the secondary 104bootstrap program, which in turn loads and runs the kernel. 105The secondary bootstrap may allow control over various boot parameters 106passed to the kernel. 107.Pp 108Some platform 109.Pq Fl m Ar machine 110and file system type 111.Pq Fl t Ar fstype 112combinations require that the name of the secondary bootstrap is 113supplied as 114.Ar secondary , 115so that information such as the disk block numbers occupied 116by the secondary bootstrap can be stored in the primary bootstrap. 117These are: 118.Bl -column "Platform" "File systems" -offset indent 119.It Sy "Platform" Ta Sy "File systems" 120.It sparc Ta ffs 121.It sun2 Ta ffs 122.El 123.Pp 124Perform the following steps to make a file system bootable: 125.Bl -enum 126.It 127Copy the secondary bootstrap (usually 128.Pa /usr/mdec/boot. Ns Sy MACHINE ) 129to the root directory of the target file system. 130.Pp 131.Nx Ns Tn /pmax 132requires that this file system starts at block 0 of the disk. 133.Pp 134The secondary 135.Nx Ns Tn /sparc64 136bootstrap is located in 137.Pa /usr/mdec/ofwboot . 138. 139.It 140Use 141.Nm 142to install the primary bootstrap program 143(usually 144.Pa /usr/mdec/bootxx. Ns Sy <fs> ) 145into 146.Ar filesystem . 147.Pp 148The following platforms do not require this step if the primary bootstrap 149already exists and the secondary bootstrap file is just being updated: 150.Em alpha , 151.Em pmax , 152.Em sparc64 , 153and 154.Em vax . 155.Pp 156The primary 157.Nx Ns Tn /sparc64 158bootstrap is located in 159.Pa /usr/mdec/bootblk . 160.El 161.Pp 162The options recognized by 163.Nm 164are as follows: 165. 166.Bl -tag -width "foobar" 167. 168.It Fl b Ar bno 169Install 170.Ar primary 171at block number 172.Ar bno 173instead of the default location for the machine and file system type. 174. 175.It Fl c 176Clear (remove) any existing bootstrap instead of installing one. 177. 178.It Fl m Ar machine 179Use 180.Ar machine 181as the target machine type. 182The default machine is determined from 183.Xr uname 3 184and then 185.Ev MACHINE . 186The following machines are currently supported by 187.Nm "" : 188.Bd -ragged -offset indent 189.Sy alpha , 190.Sy pmax , 191.Sy sparc , 192.Sy sparc64 , 193.Sy sun2 , 194.Sy vax 195.Ed 196. 197. 198.It Fl n 199Do not write to 200.Ar filesystem . 201. 202.It Fl o Ar options 203Machine specific 204.Nm 205options, comma separated. 206.Pp 207Supported options are (with the machines for they are valid in brackets): 208. 209.Bl -tag -offset indent -width alphasum 210. 211.It Sy alphasum 212.Em [ alpha ] 213Recalculate and restore the Alpha checksum. 214This is the default for 215.Nx Ns Tn /alpha . 216. 217.It Sy append 218.Em [ pmax , 219.Em vax ] 220Append 221.Ar primary 222to the end of 223.Ar filesystem , 224which must be a regular file in this case. 225. 226.It Sy sunsum 227.Em [ pmax , 228.Em vax ] 229Recalculate and restore the Sun and 230.Nx Ns Tn /sparc 231compatible checksum. 232.Em Note : 233The existing 234.Nx Ns Tn /sparc 235disklabel should use no more than 4 partitions. 236.El 237. 238.It Fl t Ar fstype 239Use 240.Ar fstype 241as the type of 242.Ar filesystem . 243The default operation is to attempt to auto-detect this setting. 244The following file system types are currently supported by 245.Nm "" : 246. 247.Bl -tag -offset indent -width ffs 248. 249.It Sy ffs 250.Bx 251Fast File System. 252. 253.It Sy raw 254.Sq Raw 255image. 256Note: the block offset of the secondary bootstrap cannot be searched 257for on this file system type. 258.El 259. 260.It Fl v 261Verbose operation. 262.El 263.Pp 264.Nm 265exits 0 on success, and \*[Gt]0 if an error occurs. 266. 267.Sh ENVIRONMENT 268.Nm 269uses the following environment variables: 270. 271.Bl -tag -width "MACHINE" 272. 273.It Ev MACHINE 274Default value for 275.Ar machine , 276overriding the result from 277.Xr uname 3 . 278. 279.El 280. 281.Sh FILES 282Most NetBSD ports will contain variations of the following files: 283.Pp 284.Bl -tag -width /usr/mdec/boot.$MACHINE 285. 286.It Pa /usr/mdec/bootxx_ Ns Sy <fs> 287Primary bootstrap for file system type 288.Sy <fs> . 289Installed into the bootstrap area of the file system by 290.Nm "" . 291. 292.It Pa /usr/mdec/boot. Ns Sy MACHINE 293Secondary bootstrap for machine type 294.Sy MACHINE . 295This should be installed into the file system before 296.Nm 297is run. 298. 299.It Pa /boot. Ns Sy MACHINE 300Installed copy of secondary bootstrap for machine type 301.Sy MACHINE . 302. 303.It Pa /boot 304Installed copy of secondary bootstrap. 305Searched for by the primary bootstrap if 306.Pa /boot. Ns Sy MACHINE 307is not found. 308. 309.El 310.Pp 311.Ss NetBSD/sparc64 files 312. 313.Bl -tag -width /usr/mdec/boot.$MACHINE 314. 315.It Pa /usr/mdec/bootblk 316.Nx Ns Tn /sparc64 317primary bootstrap. 318. 319.It Pa /usr/mdec/ofwboot 320.Nx Ns Tn /sparc64 321secondary bootstrap. 322. 323.It Pa /ofwboot 324Installed copy of 325.Nx Ns Tn /sparc64 326secondary bootstrap. 327. 328.El 329. 330.Sh EXAMPLES 331.Ss NetBSD/pmax examples 332Install the Berkeley Fast File System primary bootstrap on to disk 333.Sq sd0 : 334.D1 Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 335.Pp 336Remove the primary bootstrap from disk 337.Sq sd1 : 338.Dl Ic installboot -c /dev/swd1c 339.Pp 340Install the ISO 9660 primary bootstrap in the file 341.Pa /tmp/cd-image : 342.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 343.Pp 344Make an ISO 9660 filesystem in the file 345.Pa /tmp/cd-image 346and install the ISO 9660 primary bootstrap in the filesystem, where the 347source directory for the ISO 9660 filesystem contains a kernel, the 348primary bootstrap 349.Pa bootxx_cd9660 350and the secondary bootstrap 351.Pa boot.pmax : 352.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 353.Dl ... 354.Dl 48 51 iso-source-dir/bootxx_cd9660 355.Dl ... 356.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 357. 358.Ss NetBSD/sun2 examples 359Verbosely install the Berkeley Fast File System primary bootstrap on to 360disk 361.Sq sd0 , 362with the secondary bootstrap 363.Sq Pa /boot 364already present: 365.D1 Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs /boot 366.Sh SEE ALSO 367.Xr uname 3 , 368.Xr boot 8 , 369.Xr disklabel 8 , 370.Xr init 8 371. 372.Sh HISTORY 373This implementation of 374.Nm 375appeared in 376.Nx 1.6 . 377. 378.Sh AUTHORS 379The machine independent portion of this implementation of 380.Nm 381was written by Luke Mewburn. 382The following people contributed to the various machine dependent 383back-ends: 384Simon Burge (pmax), 385Chris Demetriou (alpha), 386Matthew Fredette (sun2), 387Paul Kranenburg (sparc), 388Matthew Green (sparc64), 389Ross Harvey (alpha), 390and 391Matt Thomas (vax). 392. 393.Sh BUGS 394There are not currently primary bootstraps to support all file systems 395types which are capable of being the root file system. 396.Ss NetBSD/pmax bugs 397The 398.Nx Ns Tn /pmax 399secondary bootstrap program can only load kernels from file 400systems starting at the beginning of disks. 401.Pp 402The size of primary bootstrap programs is restricted to 7.5KB, even 403though some file systems (e.g. ISO 9660) are able to accommodate larger 404ones. 405