1.\" $NetBSD: installboot.8,v 1.22 2002/06/30 12:49:29 wiz 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 June 30, 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 [ pmax , 243.Sy vax ] 244Append 245.Ar primary 246to the end of 247.Ar filesystem , 248which must be a regular file in this case. 249. 250.It Sy sunsum 251.Sy [ pmax , 252.Sy vax ] 253Recalculate and restore the Sun and 254.Nx Ns Tn /sparc 255compatible checksum. 256.Em Note : 257The existing 258.Nx Ns Tn /sparc 259disklabel should use no more than 4 partitions. 260.El 261. 262.It Fl t Ar fstype 263Use 264.Ar fstype 265as the type of 266.Ar filesystem . 267The default operation is to attempt to auto-detect this setting. 268The following file system types are currently supported by 269.Nm "" : 270. 271.Bl -tag -offset indent -width ffs 272. 273.It Sy ffs 274.Bx 275Fast File System. 276. 277.It Sy raw 278.Sq Raw 279image. 280Note: if a platform needs to hard-code the block offset of the secondary 281bootstrap, it cannot be searched for on this file system type, and must 282be provided with 283.Fl B Ar s2bno . 284.El 285. 286.It Fl v 287Verbose operation. 288.El 289.Pp 290.Nm 291exits 0 on success, and \*[Gt]0 if an error occurs. 292. 293.Sh ENVIRONMENT 294.Nm 295uses the following environment variables: 296. 297.Bl -tag -width "MACHINE" 298. 299.It Ev MACHINE 300Default value for 301.Ar machine , 302overriding the result from 303.Xr uname 3 . 304. 305.El 306. 307.Sh FILES 308Most 309.Nx 310ports will contain variations of the following files: 311.Pp 312.Bl -tag -width /usr/mdec/boot.$MACHINE 313. 314.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE 315Primary bootstrap for file system type 316.Sy FSTYPE . 317Installed into the bootstrap area of the file system by 318.Nm "" . 319. 320.It Pa /usr/mdec/boot. Ns Sy MACHINE 321Secondary bootstrap for machine type 322.Sy MACHINE . 323This should be installed into the file system before 324.Nm 325is run. 326. 327.It Pa /boot. Ns Sy MACHINE 328Installed copy of secondary bootstrap for machine type 329.Sy MACHINE . 330. 331.It Pa /boot 332Installed copy of secondary bootstrap. 333Searched for by the primary bootstrap if 334.Pa /boot. Ns Sy MACHINE 335is not found. 336. 337.El 338. 339.Ss NetBSD/sparc64 files 340. 341.Bl -tag -width /usr/mdec/boot.$MACHINE 342. 343.It Pa /usr/mdec/bootblk 344.Nx Ns Tn /sparc64 345primary bootstrap. 346. 347.It Pa /usr/mdec/ofwboot 348.Nx Ns Tn /sparc64 349secondary bootstrap. 350. 351.It Pa /ofwboot 352Installed copy of 353.Nx Ns Tn /sparc64 354secondary bootstrap. 355. 356.El 357. 358.Sh EXAMPLES 359. 360.Ss common 361Verbosely install the Berkeley Fast File System primary bootstrap on to disk 362.Sq sd0 : 363.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs 364.Pp 365Remove the primary bootstrap from disk 366.Sq sd1 : 367.Dl Ic installboot -c /dev/rsd1c 368. 369.Ss NetBSD/pmax 370Install the Berkeley Fast File System primary bootstrap on to disk 371.Sq sd0 : 372.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 373.Pp 374.Nx Ns Tn /pmax 375requires that this file system starts at block 0 of the disk. 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.Pp 387.Pa bootxx_cd9660 388and the secondary bootstrap 389.Pa boot.pmax : 390.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 391.Dl ... 392.Dl 48 51 iso-source-dir/bootxx_cd9660 393.Dl ... 394.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 395. 396.Ss NetBSD/sparc 397Install the Berkeley Fast File System primary bootstrap on to disk 398.Sq sd0 , 399with the secondary bootstrap 400.Sq Pa /boot 401already present: 402.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 403. 404.Ss NetBSD/sparc64 405Install the Berkeley Fast File System primary bootstrap on to disk 406.Sq wd0 : 407.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk 408.Pp 409The secondary 410.Nx Ns Tn /sparc64 411bootstrap is located in 412.Pa /usr/mdec/ofwboot . 413. 414.Ss NetBSD/sun2 and NetBSD/sun3 415Install the Berkeley Fast File System primary bootstrap on to disk 416.Sq sd0 , 417with the secondary bootstrap 418.Sq Pa /boot 419already present: 420.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot 421. 422.Sh SEE ALSO 423.Xr uname 3 , 424.Xr boot 8 , 425.Xr disklabel 8 426. 427.Sh HISTORY 428This implementation of 429.Nm 430appeared in 431.Nx 1.6 . 432. 433.Sh AUTHORS 434The machine independent portion of this implementation of 435.Nm 436was written by Luke Mewburn. 437The following people contributed to the various machine dependent 438back-ends: 439Simon Burge (pmax), 440Chris Demetriou (alpha), 441Matthew Fredette (sun2, sun3), 442Matthew Green (sparc64), 443Ross Harvey (alpha), 444Paul Kranenburg (sparc), 445Luke Mewburn (macppc), 446Matt Thomas (vax), 447and 448Izumi Tsutsui (news68k, newsmips). 449. 450.Sh BUGS 451There are not currently primary bootstraps to support all file systems 452types which are capable of being the root file system. 453. 454.Ss NetBSD/alpha 455The 456.Nx Ns Tn /alpha 457primary bootstrap program can only load the secondary bootstrap program 458from file systems starting at the beginning (block 0) of disks. 459Similarly, the secondary bootstrap program can only load kernels from 460file systems starting at the beginning of disks. 461.Pp 462The size of primary bootstrap programs is restricted to 7.5KB, even 463though some file systems (e.g. ISO 9660) are able to accommodate larger 464ones. 465. 466.Ss NetBSD/pmax 467The 468.Nx Ns Tn /pmax 469secondary bootstrap program can only load kernels from file 470systems starting at the beginning of disks. 471.Pp 472The size of primary bootstrap programs is restricted to 7.5KB, even 473though some file systems (e.g. ISO 9660) are able to accommodate larger 474ones. 475. 476.Ss NetBSD/sun2 and NetBSD/sun3 477The 478.Nx Ns Tn /sun2 479and 480.Nx Ns Tn /sun3 481secondary bootstrap program can only load kernels from file 482systems starting at the beginning of disks. 483. 484.Ss NetBSD/vax 485The 486.Nx Ns Tn /vax 487secondary bootstrap program can only load kernels from file systems 488starting at the beginning of disks. 489.Pp 490The size of primary bootstrap programs is restricted to 7.5KB, even 491though some file systems (e.g. ISO 9660) are able to accommodate larger 492ones. 493