495 lines
11 KiB
Groff
495 lines
11 KiB
Groff
.\" $NetBSD: installboot.8,v 1.23 2002/10/03 07:27:50 lukem Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Luke Mewburn of Wasabi Systems.
|
|
.\"
|
|
.\" 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 the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``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 FOUNDATION OR CONTRIBUTORS
|
|
.\" 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 October 3, 2002
|
|
.Dt INSTALLBOOT 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm installboot
|
|
.Nd install disk bootstrap software
|
|
.
|
|
.Sh SYNOPSIS
|
|
.Nm ""
|
|
.Op Fl nv
|
|
.Bk -words
|
|
.Op Fl m Ar machine
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl o Ar options
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl t Ar fstype
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl b Ar s1bno
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl B Ar s2bno
|
|
.Ek
|
|
.Ar filesystem
|
|
.Ar primary
|
|
.Op Ar secondary
|
|
.Nm ""
|
|
.Fl c
|
|
.Op Fl nv
|
|
.Bk -words
|
|
.Op Fl m Ar machine
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl o Ar options
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl t Ar fstype
|
|
.Ek
|
|
.Ar filesystem
|
|
.
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility installs and removes
|
|
.Nx
|
|
disk bootstrap software into a file system.
|
|
.Nm
|
|
can install
|
|
.Ar primary
|
|
into
|
|
.Ar filesystem ,
|
|
or disable an existing bootstrap in
|
|
.Ar filesystem .
|
|
.Pp
|
|
Generally,
|
|
.Nx
|
|
disk bootstrap software consists of two parts: a
|
|
.Dq primary
|
|
bootstrap program usually written into the disklabel area of the
|
|
file system by
|
|
.Nm "" ,
|
|
and a
|
|
.Dq secondary
|
|
bootstrap program that usually resides as an ordinary file in the file system.
|
|
.Pp
|
|
When booting, the primary bootstrap program is loaded and invoked by
|
|
the machine's PROM or BIOS.
|
|
After receiving control of the system it loads and runs the secondary
|
|
bootstrap program, which in turn loads and runs the kernel.
|
|
The secondary bootstrap may allow control over various boot parameters
|
|
passed to the kernel.
|
|
.Pp
|
|
Some platform
|
|
.Pq Fl m Ar machine
|
|
and file system type
|
|
.Pq Fl t Ar fstype
|
|
combinations require that the name of the secondary bootstrap is
|
|
supplied as
|
|
.Ar secondary ,
|
|
so that information such as the disk block numbers occupied
|
|
by the secondary bootstrap can be stored in the primary bootstrap.
|
|
These are:
|
|
.Bl -column "Platform" "File systems" -offset indent
|
|
.It Sy "Platform" Ta Sy "File systems"
|
|
.It macppc Ta ffs, raw
|
|
.It news68k Ta ffs, raw
|
|
.It newsmips Ta ffs, raw
|
|
.It sparc Ta ffs, raw
|
|
.It sun2 Ta ffs, raw
|
|
.It sun3 Ta ffs, raw
|
|
.El
|
|
.Pp
|
|
Perform the following steps to make a file system bootable:
|
|
.Bl -enum
|
|
.It
|
|
Copy the secondary bootstrap (usually
|
|
.Pa /usr/mdec/boot. Ns Sy MACHINE
|
|
or
|
|
.Pa /usr/mdec/boot )
|
|
to the root directory of the target file system.
|
|
.Pp
|
|
.
|
|
.It
|
|
Use
|
|
.Nm
|
|
to install the primary bootstrap program
|
|
(usually
|
|
.Pa /usr/mdec/bootxx_ Ns Sy FSTYPE )
|
|
into
|
|
.Ar filesystem .
|
|
.Pp
|
|
The following platforms do not require this step if the primary bootstrap
|
|
already exists and the secondary bootstrap file is just being updated:
|
|
.Sy alpha ,
|
|
.Sy pmax ,
|
|
.Sy sparc64 ,
|
|
and
|
|
.Sy vax .
|
|
.Pp
|
|
.El
|
|
.Pp
|
|
The options recognized by
|
|
.Nm
|
|
are as follows:
|
|
.
|
|
.Bl -tag -width "optionsxxx"
|
|
.
|
|
.It Fl b Ar s1bno
|
|
Install
|
|
.Ar primary
|
|
at block number
|
|
.Ar s1bno
|
|
instead of the default location for the machine and file system type.
|
|
.Sy [ alpha ,
|
|
.Sy pmax ,
|
|
.Sy vax ]
|
|
.
|
|
.It Fl B Ar s2bno
|
|
When hard-coding the blocks of
|
|
.Ar secondary
|
|
into
|
|
.Ar primary ,
|
|
start from block
|
|
.Ar s2bno
|
|
instead of trying to determine the block numbers occupied by
|
|
.Ar secondary
|
|
by examining
|
|
.Ar filesystem .
|
|
If this option is supplied,
|
|
.Ar secondary
|
|
should refer to an actual secondary bootstrap (rather than the
|
|
file name of the one present in
|
|
.Ar filesystem )
|
|
so that its size can be determined.
|
|
.
|
|
.It Fl c
|
|
Clear (remove) any existing bootstrap instead of installing one.
|
|
.
|
|
.It Fl m Ar machine
|
|
Use
|
|
.Ar machine
|
|
as the target machine type.
|
|
The default machine is determined from
|
|
.Xr uname 3
|
|
and then
|
|
.Ev MACHINE .
|
|
The following machines are currently supported by
|
|
.Nm "" :
|
|
.Bd -ragged -offset indent
|
|
.Sy alpha ,
|
|
.Sy macppc ,
|
|
.Sy news68k ,
|
|
.Sy newsmips ,
|
|
.Sy pmax ,
|
|
.Sy sparc ,
|
|
.Sy sparc64 ,
|
|
.Sy sun2 ,
|
|
.Sy sun3 ,
|
|
.Sy vax ,
|
|
.Sy x68k
|
|
.Ed
|
|
.
|
|
.
|
|
.It Fl n
|
|
Do not write to
|
|
.Ar filesystem .
|
|
.
|
|
.It Fl o Ar options
|
|
Machine specific
|
|
.Nm
|
|
options, comma separated.
|
|
.Pp
|
|
Supported options are (with the machines for they are valid in brackets):
|
|
.
|
|
.Bl -tag -offset indent -width alphasum
|
|
.
|
|
.It Sy alphasum
|
|
.Sy [ alpha ]
|
|
Recalculate and restore the Alpha checksum.
|
|
This is the default for
|
|
.Nx Ns Tn /alpha .
|
|
.
|
|
.It Sy append
|
|
.Sy [ alpha ,
|
|
.Sy pmax ,
|
|
.Sy vax ]
|
|
Append
|
|
.Ar primary
|
|
to the end of
|
|
.Ar filesystem ,
|
|
which must be a regular file in this case.
|
|
.
|
|
.It Sy sunsum
|
|
.Sy [ alpha ,
|
|
.Sy pmax ,
|
|
.Sy vax ]
|
|
Recalculate and restore the Sun and
|
|
.Nx Ns Tn /sparc
|
|
compatible checksum.
|
|
.Em Note :
|
|
The existing
|
|
.Nx Ns Tn /sparc
|
|
disklabel should use no more than 4 partitions.
|
|
.El
|
|
.
|
|
.It Fl t Ar fstype
|
|
Use
|
|
.Ar fstype
|
|
as the type of
|
|
.Ar filesystem .
|
|
The default operation is to attempt to auto-detect this setting.
|
|
The following file system types are currently supported by
|
|
.Nm "" :
|
|
.
|
|
.Bl -tag -offset indent -width ffs
|
|
.
|
|
.It Sy ffs
|
|
.Bx
|
|
Fast File System.
|
|
.
|
|
.It Sy raw
|
|
.Sq Raw
|
|
image.
|
|
Note: if a platform needs to hard-code the block offset of the secondary
|
|
bootstrap, it cannot be searched for on this file system type, and must
|
|
be provided with
|
|
.Fl B Ar s2bno .
|
|
.El
|
|
.
|
|
.It Fl v
|
|
Verbose operation.
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
exits 0 on success, and \*[Gt]0 if an error occurs.
|
|
.
|
|
.Sh ENVIRONMENT
|
|
.Nm
|
|
uses the following environment variables:
|
|
.
|
|
.Bl -tag -width "MACHINE"
|
|
.
|
|
.It Ev MACHINE
|
|
Default value for
|
|
.Ar machine ,
|
|
overriding the result from
|
|
.Xr uname 3 .
|
|
.
|
|
.El
|
|
.
|
|
.Sh FILES
|
|
Most
|
|
.Nx
|
|
ports will contain variations of the following files:
|
|
.Pp
|
|
.Bl -tag -width /usr/mdec/boot.$MACHINE
|
|
.
|
|
.It Pa /usr/mdec/bootxx_ Ns Sy FSTYPE
|
|
Primary bootstrap for file system type
|
|
.Sy FSTYPE .
|
|
Installed into the bootstrap area of the file system by
|
|
.Nm "" .
|
|
.
|
|
.It Pa /usr/mdec/boot. Ns Sy MACHINE
|
|
Secondary bootstrap for machine type
|
|
.Sy MACHINE .
|
|
This should be installed into the file system before
|
|
.Nm
|
|
is run.
|
|
.
|
|
.It Pa /boot. Ns Sy MACHINE
|
|
Installed copy of secondary bootstrap for machine type
|
|
.Sy MACHINE .
|
|
.
|
|
.It Pa /boot
|
|
Installed copy of secondary bootstrap.
|
|
Searched for by the primary bootstrap if
|
|
.Pa /boot. Ns Sy MACHINE
|
|
is not found.
|
|
.
|
|
.El
|
|
.
|
|
.Ss NetBSD/sparc64 files
|
|
.
|
|
.Bl -tag -width /usr/mdec/boot.$MACHINE
|
|
.
|
|
.It Pa /usr/mdec/bootblk
|
|
.Nx Ns Tn /sparc64
|
|
primary bootstrap.
|
|
.
|
|
.It Pa /usr/mdec/ofwboot
|
|
.Nx Ns Tn /sparc64
|
|
secondary bootstrap.
|
|
.
|
|
.It Pa /ofwboot
|
|
Installed copy of
|
|
.Nx Ns Tn /sparc64
|
|
secondary bootstrap.
|
|
.
|
|
.El
|
|
.
|
|
.Sh EXAMPLES
|
|
.
|
|
.Ss common
|
|
Verbosely install the Berkeley Fast File System primary bootstrap on to disk
|
|
.Sq sd0 :
|
|
.Dl Ic installboot -v /dev/rsd0c /usr/mdec/bootxx_ffs
|
|
.Pp
|
|
Remove the primary bootstrap from disk
|
|
.Sq sd1 :
|
|
.Dl Ic installboot -c /dev/rsd1c
|
|
.
|
|
.Ss NetBSD/pmax
|
|
Install the Berkeley Fast File System primary bootstrap on to disk
|
|
.Sq sd0 :
|
|
.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx_ffs
|
|
.Pp
|
|
.Nx Ns Tn /pmax
|
|
requires that this file system starts at block 0 of the disk.
|
|
.Pp
|
|
Install the ISO 9660 primary bootstrap in the file
|
|
.Pa /tmp/cd-image :
|
|
.Dl Ic installboot -m pmax /tmp/cd-image /usr/mdec/bootxx_cd9660
|
|
.Pp
|
|
Make an ISO 9660 filesystem in the file
|
|
.Pa /tmp/cd-image
|
|
and install the ISO 9660 primary bootstrap in the filesystem, where the
|
|
source directory for the ISO 9660 filesystem contains a kernel, the
|
|
primary bootstrap
|
|
.Pp
|
|
.Pa bootxx_cd9660
|
|
and the secondary bootstrap
|
|
.Pa boot.pmax :
|
|
.Dl Ic mkisofs -o /tmp/cd-image -a -l -v iso-source-dir
|
|
.Dl ...
|
|
.Dl 48 51 iso-source-dir/bootxx_cd9660
|
|
.Dl ...
|
|
.Dl Ic installboot -b `expr 48 \e* 4` /tmp/cd-image /usr/mdec/bootxx_cd9660
|
|
.
|
|
.Ss NetBSD/sparc
|
|
Install the Berkeley Fast File System primary bootstrap on to disk
|
|
.Sq sd0 ,
|
|
with the secondary bootstrap
|
|
.Sq Pa /boot
|
|
already present:
|
|
.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot
|
|
.
|
|
.Ss NetBSD/sparc64
|
|
Install the Berkeley Fast File System primary bootstrap on to disk
|
|
.Sq wd0 :
|
|
.Dl Ic installboot /dev/rwd0c /usr/mdec/bootblk
|
|
.Pp
|
|
The secondary
|
|
.Nx Ns Tn /sparc64
|
|
bootstrap is located in
|
|
.Pa /usr/mdec/ofwboot .
|
|
.
|
|
.Ss NetBSD/sun2 and NetBSD/sun3
|
|
Install the Berkeley Fast File System primary bootstrap on to disk
|
|
.Sq sd0 ,
|
|
with the secondary bootstrap
|
|
.Sq Pa /boot
|
|
already present:
|
|
.Dl Ic installboot /dev/rsd0c /usr/mdec/bootxx /boot
|
|
.
|
|
.Sh SEE ALSO
|
|
.Xr uname 3 ,
|
|
.Xr boot 8 ,
|
|
.Xr disklabel 8
|
|
.
|
|
.Sh HISTORY
|
|
This implementation of
|
|
.Nm
|
|
appeared in
|
|
.Nx 1.6 .
|
|
.
|
|
.Sh AUTHORS
|
|
The machine independent portion of this implementation of
|
|
.Nm
|
|
was written by Luke Mewburn.
|
|
The following people contributed to the various machine dependent
|
|
back-ends:
|
|
Simon Burge (pmax),
|
|
Chris Demetriou (alpha),
|
|
Matthew Fredette (sun2, sun3),
|
|
Matthew Green (sparc64),
|
|
Ross Harvey (alpha),
|
|
Paul Kranenburg (sparc),
|
|
Luke Mewburn (macppc),
|
|
Matt Thomas (vax),
|
|
and
|
|
Izumi Tsutsui (news68k, newsmips).
|
|
.
|
|
.Sh BUGS
|
|
There are not currently primary bootstraps to support all file systems
|
|
types which are capable of being the root file system.
|
|
.
|
|
.Ss NetBSD/alpha
|
|
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 accommodate larger
|
|
ones.
|
|
.
|
|
.Ss NetBSD/pmax
|
|
The
|
|
.Nx Ns Tn /pmax
|
|
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 accommodate larger
|
|
ones.
|
|
.
|
|
.Ss NetBSD/sun2 and NetBSD/sun3
|
|
The
|
|
.Nx Ns Tn /sun2
|
|
and
|
|
.Nx Ns Tn /sun3
|
|
secondary bootstrap program can only load kernels from file
|
|
systems starting at the beginning of disks.
|
|
.
|
|
.Ss NetBSD/vax
|
|
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 accommodate larger
|
|
ones.
|