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