1.\" $NetBSD: installboot.8,v 1.11 2002/04/30 14:45:12 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 April 23, 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 108Perform the following steps to make a file system bootable: 109.Bl -enum 110.It 111Copy the secondary bootstrap (usually 112.Pa /usr/mdec/boot. Ns Sy MACHINE ) 113to the root directory of the target file system. 114.Pp 115.Nx Ns Tn /pmax 116requires that this file system starts at block 0 of the disk. 117.Pp 118The secondary 119.Nx Ns Tn /sparc64 120bootstrap is located in 121.Pa /usr/mdec/ofwboot . 122. 123.It 124Use 125.Nm 126to install the primary bootstrap program 127(usually 128.Pa /usr/mdec/bootxx. Ns Sy <fs> ) 129into 130.Ar filesystem . 131.Pp 132.Nx Ns Tn /pmax 133and 134.Nx Ns Tn /sparc64 135do not require this step if the primary bootstrap already exists 136and the secondary bootstrap file is just being updated. 137.Pp 138The primary 139.Nx Ns Tn /sparc64 140bootstrap is located in 141.Pa /usr/mdec/bootblk . 142.El 143.Pp 144The options recognized by 145.Nm 146are as follows: 147. 148.Bl -tag -width "foobar" 149. 150.It Fl b Ar bno 151Install 152.Ar primary 153at block number 154.Ar bno 155instead of the default location for the machine and file system type. 156. 157.It Fl c 158Clear (remove) any existing bootstrap instead of installing one. 159. 160.It Fl m Ar machine 161Use 162.Ar machine 163as the target machine type. 164The default machine is determined from 165.Xr uname 3 166and then 167.Ev MACHINE . 168The following machines are currently supported by 169.Nm "" : 170.Bd -ragged -offset indent 171.Sy alpha , 172.Sy pmax , 173.Sy sparc64 , 174.Sy sun2 , 175.Sy vax 176.Ed 177. 178. 179.It Fl n 180Do not write to 181.Ar filesystem . 182. 183.It Fl o Ar options 184Machine specific 185.Nm 186options, comma separated. 187.Pp 188Supported options are (with the machines for they are valid in brackets): 189. 190.Bl -tag -offset indent -width alphasum 191. 192.It Sy alphasum 193.Em [ alpha ] 194Recalculate and restore the Alpha checksum. 195This is the default for 196.Nx Ns Tn /alpha . 197. 198.It Sy append 199.Em [ pmax , 200.Em vax ] 201Append 202.Ar primary 203to the end of 204.Ar filesystem , 205which must be a regular file in this case. 206. 207.It Sy sunsum 208.Em [ pmax , 209.Em vax ] 210Recalculate and restore the Sun and 211.Nx Ns Tn /sparc 212compatible checksum. 213.Em Note : 214The existing 215.Nx Ns Tn /sparc 216disklabel should use no more than 4 partitions. 217.El 218. 219.It Fl t Ar fstype 220Use 221.Ar fstype 222as the type of 223.Ar filesystem . 224The default operation is to attempt to auto-detect this setting. 225The following file system types are currently supported by 226.Nm "" : 227. 228.Bl -tag -offset indent -width ffs 229. 230.It Sy ffs 231.Bx 232Fast File System. 233. 234.It Sy raw 235.Sq Raw 236image. 237Note: the block offset of the secondary bootstrap cannot be searched 238for on this file system type. 239.El 240. 241.It Fl v 242Verbose operation. 243.El 244.Pp 245.Nm 246exits 0 on success, and \*[Gt]0 if an error occurs. 247. 248.Sh ENVIRONMENT 249.Nm 250uses the following environment variables: 251. 252.Bl -tag -width "MACHINE" 253. 254.It Ev MACHINE 255Default value for 256.Ar machine , 257overriding the result from 258.Xr uname 3 . 259. 260.El 261. 262.Sh FILES 263Most NetBSD ports will contain variations of the following files: 264.Pp 265.Bl -tag -width /usr/mdec/boot.$MACHINE 266. 267.It Pa /usr/mdec/bootxx_ Ns Sy <fs> 268Primary bootstrap for file system type 269.Sy <fs> . 270Installed into the bootstrap area of the file system by 271.Nm "" . 272. 273.It Pa /usr/mdec/boot. Ns Sy MACHINE 274Secondary bootstrap for machine type 275.Sy MACHINE . 276This should be installed into the file system before 277.Nm 278is run. 279. 280.It Pa /boot. Ns Sy MACHINE 281Installed copy of secondary bootstrap for machine type 282.Sy MACHINE . 283. 284.It Pa /boot 285Installed copy of secondary bootstrap. 286Searched for by the primary bootstrap if 287.Pa /boot. Ns Sy MACHINE 288is not found. 289. 290.El 291.Pp 292.Ss NetBSD/sparc64 files 293. 294.Bl -tag -width /usr/mdec/boot.$MACHINE 295. 296.It Pa /usr/mdec/bootblk 297.Nx Ns Tn /sparc64 298primary bootstrap. 299. 300.It Pa /usr/mdec/ofwboot 301.Nx Ns Tn /sparc64 302secondary bootstrap. 303. 304.It Pa /ofwboot 305Installed copy of 306.Nx Ns Tn /sparc64 307secondary bootstrap. 308. 309.El 310. 311.Sh EXAMPLES 312.Ss NetBSD/pmax examples 313Install the Berkeley Fast File System primary bootstrap on to disk sd0: 314.D1 Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 315.Pp 316Remove the primary bootstrap from disk sd1: 317.Dl Ic installboot -c /dev/swd1c 318.Pp 319Install the ISO 9660 primary bootstrap in the file 320.Pa /tmp/cd-image : 321.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 322.Pp 323Make an ISO 9660 filesystem in the file 324.Pa /tmp/cd-image 325and install the ISO 9660 primary bootstrap in the filesystem, where the 326source directory for the ISO 9660 filesystem contains a kernel, the 327primary bootstrap 328.Pa bootxx_cd9660 329and the secondary bootstrap 330.Pa boot.pmax : 331.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 332.Dl ... 333.Dl 48 51 iso-source-dir/bootxx_cd9660 334.Dl ... 335.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 336. 337.Sh SEE ALSO 338.Xr uname 3 , 339.Xr boot 8 , 340.Xr disklabel 8 , 341.Xr init 8 342. 343.Sh HISTORY 344This implementation of 345.Nm 346appeared in 347.Nx 1.6 . 348. 349.Sh AUTHORS 350The machine independent portion of this implementation of 351.Nm 352was written by Luke Mewburn. 353The following people contributed to the various machine dependent 354back-ends: 355Simon Burge (pmax), 356Chris Demetriou (alpha), 357Matthew Fredette (sun2), 358Matthew Green (sparc64), 359Ross Harvey (alpha), 360and 361Matt Thomas (vax). 362. 363.Sh BUGS 364There are not currently primary bootstraps to support all file systems 365types which are capable of being the root file system. 366.Ss NetBSD/pmax bugs 367The 368.Nx Ns Tn /pmax 369secondary bootstrap program can only load kernels from file 370systems starting at the beginning of disks. 371.Pp 372The size of primary bootstrap programs is restricted to 7.5KB, even 373though some file systems (e.g. ISO 9660) are able to accommodate larger 374ones. 375