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