1.\" $NetBSD: installboot.8,v 1.18 2002/05/20 20:24:49 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 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.Ed 228. 229. 230.It Fl n 231Do not write to 232.Ar filesystem . 233. 234.It Fl o Ar options 235Machine specific 236.Nm 237options, comma separated. 238.Pp 239Supported options are (with the machines for they are valid in brackets): 240. 241.Bl -tag -offset indent -width alphasum 242. 243.It Sy alphasum 244.Sy [ alpha ] 245Recalculate and restore the Alpha checksum. 246This is the default for 247.Nx Ns Tn /alpha . 248. 249.It Sy append 250.Sy [ pmax , 251.Sy vax ] 252Append 253.Ar primary 254to the end of 255.Ar filesystem , 256which must be a regular file in this case. 257. 258.It Sy sunsum 259.Sy [ pmax , 260.Sy vax ] 261Recalculate and restore the Sun and 262.Nx Ns Tn /sparc 263compatible checksum. 264.Em Note : 265The existing 266.Nx Ns Tn /sparc 267disklabel should use no more than 4 partitions. 268.El 269. 270.It Fl t Ar fstype 271Use 272.Ar fstype 273as the type of 274.Ar filesystem . 275The default operation is to attempt to auto-detect this setting. 276The following file system types are currently supported by 277.Nm "" : 278. 279.Bl -tag -offset indent -width ffs 280. 281.It Sy ffs 282.Bx 283Fast File System. 284. 285.It Sy raw 286.Sq Raw 287image. 288Note: if a platform needs to hard-code the block offset of the secondary 289bootstrap, it cannot be searched for on this file system type, and must 290be provided with 291.Fl B Ar s2bno . 292.El 293. 294.It Fl v 295Verbose operation. 296.El 297.Pp 298.Nm 299exits 0 on success, and \*[Gt]0 if an error occurs. 300. 301.Sh ENVIRONMENT 302.Nm 303uses the following environment variables: 304. 305.Bl -tag -width "MACHINE" 306. 307.It Ev MACHINE 308Default value for 309.Ar machine , 310overriding the result from 311.Xr uname 3 . 312. 313.El 314. 315.Sh FILES 316Most 317.Nx 318ports will contain variations of the following files: 319.Pp 320.Bl -tag -width /usr/mdec/boot.$MACHINE 321. 322.It Pa /usr/mdec/bootxx_ Ns Sy <fs> 323Primary bootstrap for file system type 324.Sy <fs> . 325Installed into the bootstrap area of the file system by 326.Nm "" . 327. 328.It Pa /usr/mdec/boot. Ns Sy MACHINE 329Secondary bootstrap for machine type 330.Sy MACHINE . 331This should be installed into the file system before 332.Nm 333is run. 334. 335.It Pa /boot. Ns Sy MACHINE 336Installed copy of secondary bootstrap for machine type 337.Sy MACHINE . 338. 339.It Pa /boot 340Installed copy of secondary bootstrap. 341Searched for by the primary bootstrap if 342.Pa /boot. Ns Sy MACHINE 343is not found. 344. 345.El 346. 347.Ss NetBSD/sparc64 files 348. 349.Bl -tag -width /usr/mdec/boot.$MACHINE 350. 351.It Pa /usr/mdec/bootblk 352.Nx Ns Tn /sparc64 353primary bootstrap. 354. 355.It Pa /usr/mdec/ofwboot 356.Nx Ns Tn /sparc64 357secondary bootstrap. 358. 359.It Pa /ofwboot 360Installed copy of 361.Nx Ns Tn /sparc64 362secondary bootstrap. 363. 364.El 365. 366.Sh EXAMPLES 367.Ss NetBSD/pmax examples 368Install the Berkeley Fast File System primary bootstrap on to disk 369.Sq sd0 : 370.D1 Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs 371.Pp 372Remove the primary bootstrap from disk 373.Sq sd1 : 374.Dl Ic installboot -c /dev/swd1c 375.Pp 376Install the ISO 9660 primary bootstrap in the file 377.Pa /tmp/cd-image : 378.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660 379.Pp 380Make an ISO 9660 filesystem in the file 381.Pa /tmp/cd-image 382and install the ISO 9660 primary bootstrap in the filesystem, where the 383source directory for the ISO 9660 filesystem contains a kernel, the 384primary bootstrap 385.Pa bootxx_cd9660 386and the secondary bootstrap 387.Pa boot.pmax : 388.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir 389.Dl ... 390.Dl 48 51 iso-source-dir/bootxx_cd9660 391.Dl ... 392.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660 393. 394.Ss NetBSD/sun2 examples 395Verbosely install the Berkeley Fast File System primary bootstrap on to 396disk 397.Sq sd0 , 398with the secondary bootstrap 399.Sq Pa /boot 400already present: 401.D1 Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs /boot 402.Sh SEE ALSO 403.Xr uname 3 , 404.Xr boot 8 , 405.Xr disklabel 8 , 406.Xr init 8 407. 408.Sh HISTORY 409This implementation of 410.Nm 411appeared in 412.Nx 1.6 . 413. 414.Sh AUTHORS 415The machine independent portion of this implementation of 416.Nm 417was written by Luke Mewburn. 418The following people contributed to the various machine dependent 419back-ends: 420Simon Burge (pmax), 421Chris Demetriou (alpha), 422Matthew Fredette (sun2, sun3), 423Matthew Green (sparc64), 424Ross Harvey (alpha), 425Paul Kranenburg (sparc), 426Luke Mewburn (macppc), 427Matt Thomas (vax), 428and 429Izumi Tsutsui (news68k, newsmips). 430. 431.Sh BUGS 432There are not currently primary bootstraps to support all file systems 433types which are capable of being the root file system. 434.Ss NetBSD/pmax bugs 435The 436.Nx Ns Tn /pmax 437secondary bootstrap program can only load kernels from file 438systems starting at the beginning of disks. 439.Pp 440The size of primary bootstrap programs is restricted to 7.5KB, even 441though some file systems (e.g. ISO 9660) are able to accommodate larger 442ones. 443