NetBSD/share/man/man8/man8.vax/installboot.8

.\" $NetBSD: installboot.8,v 1.10 2000/10/17 22:14:44 dmcmahill 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 for the
.\"          NetBSD Project.  See http://www.netbsd.org/ for
.\"          information about NetBSD.
.\" 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.
.\" 
.\" <<Id: LICENSE,v 1.2 2000/06/14 15:57:33 cgd Exp>>
.\"
.Dd April 3, 1999
.Dt INSTALLBOOT 8 vax
.Os
.Sh NAME
.Nm installboot
.Nd install and remove vax disk and CD-ROM bootstrap software
.Sh SYNOPSIS
.Nm /usr/mdec/installboot
.Op Fl a | Fl i Ar isoblock
.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 /vax
disk and CD-ROM bootstrap software.  Installing bootstrap
software on a device allows the DECstation PROM to boot from that
device.  As far as the PROM 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 /vax
disk bootstrap software consists of two parts: a
.Dq primary
bootstrap program usually written into the disklabel area of the
disk, and a
.Dq secondary
bootstrap program that usually resides in a file system on the disk.
When booting, the primary bootstrap program is loaded and invoked by
the PROM.  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 /vax
disk bootable by the PROM, 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.vax
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.vax
in the root directory of the file system which contains it.
Note that is is not 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 a
Append the primary bootstrap to the end of
.Ar disk .
.Em Note :
this option can be used only if
.Ar disk
is a regular file.
.It Fl c
Instead of installing a primary bootstrap program, remove any existing
primary bootstrap program.
.It Fl i Ar isoblock
Install the primary bootstrap at ISO block number
.Ar isoblock
in the ISO filesystem on
.Ar disk .
See the
.Nm EXAMPLES
section below for an example of this option.
.It Fl n
Do not actually write anything to the disk.
.It Fl s
Recalculate and restore the Sun and
.Nx Ns Tn /sparc
compatible checksum.  This option is used
when making an ISO image which will boot on both 
.Nx Ns Tn /sparc 
and 
.Nx Ns Tn /vax. 
.Em Note : No The existing
.Nx Ns Tn /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/boot.vax -compact
.It Pa /usr/mdec/bootxx
primary bootstrap program
.It Pa /usr/mdec/boot.vax
secondary bootstrap
.It Pa /boot.vax
secondary bootstrap (installed)
.El
.Sh EXAMPLES
.Pp
.if t .ne 4
Install the primary bootstrap to disk sd0:
.D1 Ic /usr/mdec/installboot /dev/rsd0c /usr/mdec/bootxx
.Pp
Remove the primary bootstrap from disk sd1:
.Dl Ic /usr/mdec/installboot -c /dev/rsd1c
.Pp
Install the primary bootstrap in the file
.Pa /tmp/cd-image :
.Dl Ic /usr/mdec/installboot /tmp/cd-image /usr/mdec/bootxx
.Pp
Make an ISO 9660 filesystem in the file
.Pa /tmp/cd-image
and install the primary bootstrap in the filesystem, where the
source directory for the ISO 9660 filesystem contains a kernel, the
primary bootstrap
.Pa bootxx
and the secondary bootstrap
.Pa boot.vax :
.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir
.Dl Li ...
.Dl Li 48 51 iso-source-dir/bootxx
.Dl Li ...
.Dl Ic /usr/mdec/installboot -i 48 /tmp/cd-image /usr/mdec/bootxx
.Sh SEE ALSO
.Xr boot 8 ,
.Xr mkbootimage 8
.Sh HISTORY
The
.Nx Ns Tn /vax
.Nm
first appeared in
.Nx 1.5 ,
and is based on the
.Nx Ns Tn /pmax
.Nm
command that first appeared in
.Nx 1.5 .
.Sh AUTHORS
The
.Nx Ns Tn /vax
modifications to the
.Nm
command were written by Matt Thomas.  The
.Nx Ns Tn /alpha
.Nm
version of this utility was written by Chris Demetriou and Ross Harvey.
The
.Nx Ns Tn /alpha
.Nm
version was modified to produce the
.Nx Ns Tn /pmax
.Nm
by Simon Burge which formed the starting point for this program.  
.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 /vax
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.