.\" $NetBSD: installboot.8,v 1.16 1999/10/04 19:20:33 ross Exp $
.\"
.\" Copyright (c) 1999 Christopher G. Demetriou.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Christopher G. Demetriou
.\"      for the NetBSD Project.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 3, 1999
.Dt INSTALLBOOT 8 alpha
.Os
.Sh NAME
.Nm installboot
.Nd install and remove Alpha disk and CD-ROM bootstrap software
.Sh SYNOPSIS
.Nm /usr/mdec/installboot
.Op Fl nsv
.Ar disk
.Ar bootstrap
.Nm /usr/mdec/installboot
.Op Fl nsv
.Fl c
.Ar disk
.Sh DESCRIPTION
The
.Nm
utility installs and removes
.Nx Ns Tn /alpha
disk and CD-ROM bootstrap software.  Installing bootstrap
software on a device allows the SRM console to boot from
that device.  As far as the console is concerned, booting
from disk, CD-ROM, and other random-access block devices
is the same; in the rest of this manual page, unless
otherwise noted, the description applies equally to both
disks and CD-ROMs.
.Pp
.Nx Ns Tn /alpha
disk bootstrap software consists of two parts: a
.Dq primary
bootstrap program written into the disklabel area of the disk, and a
.Dq secondary
bootstrap program that resides in a file system on the disk.
When booting, the primary bootstrap program is loaded and
invoked by the console.  After receiving control of the system
it loads and runs the secondary bootstrap program, which in turn
loads and runs the kernel.
.Pp
To make a
.Nx Ns Tn /alpha
disk bootable by the SRM console, use
.Nm
to install a primary bootstrap program on the disk's raw
.Pq Dq c
partition.
Then copy the secondary bootstrap program
.Pa /usr/mdec/boot
to the root directory of the file system that starts at the
beginning (block 0) of the disk.
Note that the primary bootstrap program used must support the type of
file system which contains the secondary bootstrap program, and that
the secondary bootstrap program must be named
.Dq boot
in the root directory of the file system which contains it.
(Unlike previous versions of
.Nm installboot ,
it is no longer necessary to run installboot after changing
the secondary bootstrap program.)
.Pp
The options recognized by
.Nm
are as follows:
.Bl -tag -width flag
.It Fl c
Instead of installing a primary bootstrap program, remove any existing
primary bootstrap program.
.It Fl n
Do not actually write anything to the disk.
.It Fl s
Arrange for the final checksum to be Sun and
.Nx Ns /sparc Ns -compatible .
.if 0 \{\
by modifying the sector interior so
the alpha 64-bit checksum also contains the embedded 16-bit sum and
16-bit magic number expected by such systems.
.\}
.Em Note : No The existing
.Nx Ns /sparc
disklabel should use no more than 4 partitions.
.It Fl v
Print information about what
.Nm
is doing.
.El
.Pp
The arguments given to
.Nm
are as follows:
.Bl -tag -width bootstrap
.It Ar disk
The name of the disk on which to install the primary
bootstrap program.  Typically this will be the raw disk device belonging
to the disk containing the file system which holds the secondary
bootstrap program.  In some cases this can be a file, e.g. if
.Nm
is being used to install the primary bootstrap program into a
file containing a ISO 9660 CD-ROM image.
.It Ar bootstrap
The primary bootstrap program to install.  (This argument
may not be specified if the
.Fl c
flag is being used.)
.El
.Pp
The
.Nm
utility exits 0 on success, and >0 if an error occurs.
.Sh FILES
.Bl -tag -width /usr/mdec/bootxx_cd9660 -compact
.It Pa /usr/mdec/bootxx_cd9660
primary bootstrap for
.Dq cd9660
(ISO 9660) file system
.It Pa /usr/mdec/bootxx_ffs
primary bootstrap for
.Dq ffs
file system
(Berkeley Fast File System)
.It Pa /usr/mdec/bootxx_lfs
primary bootstrap for
.Dq lfs
file system
(BSD Log-Structured File System)
.It Pa /usr/mdec/boot
secondary bootstrap
.El
.Sh EXAMPLES
.Pp
.if t .ne 4
Install the Berkeley Fast File System primary bootstrap on to disk sd0:
.D1 Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs
.Pp
Remove the primary bootstrap from disk sd1:
.Dl Ic installboot -c /dev/rsd1c
.Pp
Install the ISO 9660 primary bootstrap in the file
.Pa /tmp/cd-image :
.Dl Ic installboot /tmp/cd-image /usr/mdec/bootxx_cd9660
.Sh SEE ALSO
.Xr boot 8 ,
.Xr mkbootimage 8
.Sh HISTORY
The current version of the
.Nx Ns Tn /alpha
.Nm
command first appeared in
.Nx 1.4 .
A previous version which operated quite differently was introduced in
.Nx 1.2 .
.Sh AUTHORS
The
.Nm
utility was written by Chris Demetriou and Ross Harvey.
.if 0 \{\
The previous version of the
.Nx Ns Tn /alpha
.Nm
utility was originally written by Paul Kranenburg for
.Nx Ns Tn /sparc
and modified for use with
.Nx Ns Tn /alpha
by Chris Demetriou, Jason Thorpe, Ross Harvey, and others.
.\}
.Sh BUGS
The
.Nx Ns Tn /alpha
primary bootstrap program can only load the secondary bootstrap
program from file systems starting at the beginning (block 0)
of disks.  Similarly, the secondary bootstrap program can only
load kernels from file systems starting at the beginning of disks.
.Pp
The size of primary bootstrap programs is restricted to 7.5KB, even
though some file systems (e.g. ISO 9660) are able to accomodate larger
ones.
.Pp
There are not currently primary bootstraps to support all file systems
types which are capable of being the root file system.