INSTALLBOOT(8) | System Manager's Manual | INSTALLBOOT(8) |
installboot
—
install disk bootstrap software
installboot |
[-fnv ] [-B
s2bno] [-b
s1bno] [-m
machine] [-o
options] [-t
fstype] [-u
U-Boot-paths] filesystem
primary [secondary] |
installboot |
-c [-fnv ]
[-m machine]
[-o options]
[-t fstype]
filesystem |
installboot |
-e [-fnv ]
[-m machine]
[-o options]
bootstrap |
The installboot
utility installs and
removes NetBSD disk bootstrap software into a file
system. installboot
can install
primary into filesystem, or
disable an existing bootstrap in filesystem.
Generally, NetBSD disk bootstrap software
consists of two parts: a “primary” bootstrap program usually
written into the disklabel area of the file system by
installboot
, and a “secondary”
bootstrap program that usually resides as an ordinary file in the file
system.
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.
Perform the following steps to make a file system bootable:
installboot
to install the primary bootstrap
program (usually
/usr/mdec/bootxx_⟨FSTYPE⟩)
into filesystem.
The following platforms do not require this step if the primary bootstrap already exists and the secondary bootstrap file is just being updated: alpha, amd64, amiga, i386, pmax, sparc64, and vax.
The following platform does not require the first step since a single bootstrap file is used. The single bootstrap is installed like the primary bootstrap on other platforms: next68k.
On some architectures the options of an existing installed bootstrap, or those of a bootstrap file can be changed. Installing a new primary bootstrap will reset those options to default values.
Some platforms, typically embedded system platforms, are umbrella
platforms that support many different individual board types, each with
their own boot loader binary and installation procedure requirements. On
these platforms, it may be necessary to provide specific board type
information to installboot
. Information about known
boards and their requirements is loaded from a database at run-time.
Sometimes these platforms also require the use of 3rd-party boot loader
software, such as U‐Boot. To support these platforms,
installboot
scans known locations for these
3rd-party boot loader packages for database overlays that contain additional
board-specific boot loader installation information in a file called
installboot.plist.
The following platforms have this requirement and utilize this database overlay feature: evbarm.
On platforms that boot with UEFI, there is a single boot loader in
the EFI system partition at
EFI/boot/boot⟨ARCH⟩.efi
where ARCH is the UEFI name for the architecture, such
as ia32
(NetBSD/i386),
x64
(NetBSD/amd64), or
aa64
(NetBSD/aarch64).
installboot
is not needed for
UEFI boot. However, it may be used on a platform that supports UEFI boot to
make a hybrid image that can be booted
either with UEFI
boot or with, e.g., BIOS or U‐Boot. Hybrid images may also require a
special GPT for BIOS boot; see
gpt(8).
The options and arguments recognized by
installboot
are as follows:
-B
s2bno-b
s1bno-c
-e
-v
and without -o
, show
the current options. [amd64,
i386]-f
installboot
to ignore some errors.-m
machineMACHINE
environment variable. The following
machines are currently supported:
alpha
,
amd64
, amiga
,
evbarm
, ews4800mips
,
hp300
, hppa
,
i386
, landisk
,
macppc
, news68k
,
newsmips
, next68k
,
pmax
, sparc
,
sparc64
, sun2
,
sun3
, vax
,
x68k
-n
-o
optionsinstallboot
options, comma
separated.
Supported options are (with the machines for they are valid in brackets):
alphasum
append
board
[=
type]installboot
will attempt to guess the board
type based on system information if run natively.bootconf
command
=
commandlineconsole
=
namepc
, com0
,
com1
, com2
,
com3
, com0kbd
,
com1kbd
, com2kbd
,
com3kbd
, or auto
.dtb
=
dtbfileboard
and dtb
options are specified,
board
takes precedence.ioaddr
=
ioaddrkeymap
=
keymapzyz
would swap the
lowercase letters ⟨y⟩ and ⟨z⟩.media
=
typesdmmc
, emmc
,
usb
.modules
password
=
passwordresetvideo
speed
=
baudsunsum
timeout
=
seconds-t
fstype-u
U-Boot-pathsinstallboot
installation overlays. If multiple
overlays are found, overlays from paths closer to the front of the list
take precedence. If not specified, environment variable
INSTALLBOOT_UBOOT_PATHS
is used if defined;
otherwise, the default path is
/usr/pkg/share/u-boot. This option is only used on
platforms that support using U‐Boot.-v
installboot
is to operate on. It is not necessary
for filesystem to be a currently mounted file
system./
’ is not necessary on
secondary.
Only certain combinations of platform
(-m
machine) and file
system type (-t
fstype)
require that the name of the secondary bootstrap is supplied as
secondary, so that information such as the disk
block numbers occupied by the secondary bootstrap can be stored in the
primary bootstrap. These are:
Platform | File systems |
macppc | ffs, raw |
news68k | ffs, raw |
newsmips | ffs, raw |
sparc | ffs, raid, raw |
sun2 | ffs, raw |
sun3 | ffs, raw |
INSTALLBOOT_UBOOT_PATHS
installboot
installation overlays. If
multiple overlays are found, overlays from paths closer to the front of
the list take precedence. If not specified, the default path is
/usr/pkg/share/u-boot. This environment variable
is only used on platforms that support using U‐Boot.MACHINE
Most NetBSD ports will contain variations of the following files:
installboot
.-b
s1bno option.installboot
is run.The NetBSD/evbarm platform covers a wide
variety of board types, many of which use U‐Boot. Running
installboot
with no options will display a list of
known boards. Using the verbose option will also display information about
which U‐Boot package needs to be installed to support that board, and
if the required U‐Boot package is installed, the path at which it is
located.
The NetBSD/evbmips bootstrap files currently only apply to the SBMIPS kernels for the SiByte/Broadcom BCM1250 and BCM1480 CPUs. There is also U‐Boot support for the Creator CI20.
Verbosely install the Berkeley Fast File System primary bootstrap
on to disk ‘sd0
’:
installboot -v /dev/rsd0c
/usr/mdec/bootxx_ffs
Note: the “whole disk” partition
(‘c
’ on some ports,
‘d
’ on others) is used here, since the
‘a
’ partition probably is already
opened (mounted as /), so
installboot
would not be able to access it.
Remove the primary bootstrap from disk
‘sd1
’:
installboot -c
/dev/rsd1c
Modify the command line to change the default from
‘netbsd -ASn2
’ to
‘netbsd -S
’:
installboot -m amiga -o command="netbsd -S" /dev/rsd0a \ /usr/mdec/bootxx_ffsv1
Install the U‐Boot boot loader for a Pinebook into an image that will be written to an SDMMC card:
installboot -m evbarm -o
board=pine64,pinebook arm64.img
Install/update the U‐Boot boot loader for the current
running system on the eMMC device
‘ld0
’ and display verbose information
about the procedure:
installboot -v
/dev/rld0c
Install a specific U‐Boot package for a BeagleBone Black into an image that will be written to an SDMMC card:
installboot -m evbarm -o board=ti,am335x-bone-black armv7.img \ /path/to/experimental/u-boot/package
Install the System V Boot File System primary bootstrap on to disk
‘sd0
’, with the secondary bootstrap
/boot already present in the SysVBFS partition on
the disk:
installboot /dev/rsd0p
/usr/mdec/bootxx_bfs
p
’ partition is the “whole
disk” (i.e., raw) partition.Install new boot blocks on an existing FFSv2 mounted root file
system on ‘wd0
’, setting the timeout
to five seconds, after installing an MBR bootcode and copying a new
secondary bootstrap:
fdisk -c /usr/mdec/mbr
/dev/rwd0d
cp /usr/mdec/boot /boot
installboot -v -o timeout=5
/dev/rwd0a /usr/mdec/bootxx_ffsv2
Create a bootable CD-ROM with an ISO 9660 file system for an i386 system with a serial console:
mkdir cdrom cp sys/arch/i386/compile/mykernel/netbsd cdrom/netbsd cp /usr/mdec/boot cdrom/boot cp /usr/mdec/bootxx_cd9660 bootxx installboot -o console=com0,speed=19200 -m i386 -e bootxx makefs -t cd9660 -o 'bootimage=i386;bootxx,no-emul-boot' boot.iso \ cdrom
Create a bootable floppy disk with an FFSv1 file system for a small custom kernel (note: bigger kernels needing multiple disks are handled with the ustarfs file system):
newfs -s 1440k
/dev/rfd0a
mount /dev/fd0a /mnt cp /usr/mdec/boot /mnt/boot gzip -9 < sys/arch/i386/compile/mykernel/netbsd > /mnt/netbsd.gz umount /mnt installboot -v /dev/rfd0a /usr/mdec/bootxx_ffsv1
Create a bootable FAT file system on
‘wd1a
’, which should have the same
offset and size as a FAT primary partition in the Master Boot Record
(MBR):
newfs_msdos -r 16
/dev/rwd1a
-r
16
is to reserve space
for the primary bootstrap.
newfs_msdos(8) will display
an “MBR type” such as ‘1
’,
‘4
’, or
‘6
’; the MBR partition type of the
appropriate primary partition should be changed to this value.mount -t msdos /dev/wd1a /mnt cp /usr/mdec/boot /mnt/boot cp path/to/kernel /mnt/netbsd umount /mnt installboot -t raw /dev/rwd1a /usr/mdec/bootxx_msdos
Make the existing FAT16 filesystem on
‘sd0e
’ bootable. This can be used to
make USB memory bootable provided it has 512 byte sectors and that the
manufacturer correctly initialised the file system.
mount -t msdos /dev/sd0e /mnt cp /usr/mdec/boot /mnt/boot cp path/to/kernel /mnt/netbsd umount /mnt installboot /dev/rsd0e /usr/mdec/bootxx_fat16
It may also be necessary to use fdisk(8) to make the device itself bootable.
Switch the existing installed bootstrap to use a serial console without reinstalling or altering other options such as timeout.
installboot -e -o console=com0
/dev/rwd0a
Note the installboot
utility is only
required for macppc machines with OpenFirmware version 2 to boot.
OpenFirmware 3 cannot load bootblocks specified in the Apple partition
map.
Install the Berkeley Fast File System primary bootstrap on to disk
‘wd0
’:
installboot /dev/rwd0c
/usr/mdec/bootxx /ofwboot
The secondary NetBSD/macppc bootstrap is located in /usr/mdec/ofwboot.
The primary bootstrap requires the raw ofwboot for the secondary bootstrap, not ofwboot.xcf, which is used for the OpenFirmware to load kernels.
Install the bootstrap on to disk
‘sd0
’:
installboot /dev/rsd0c
/usr/mdec/boot
Install the Berkeley Fast File System primary bootstrap on to disk
‘sd0
’:
installboot /dev/rsd0c
/usr/mdec/bootxx_ffs
NetBSD/pmax requires that this file system starts at block 0 of the disk.
Install the ISO 9660 primary bootstrap in the file /tmp/cd-image:
installboot -m pmax /tmp/cd-image
/usr/mdec/bootxx_cd9660
Make an ISO 9660 filesystem in the file /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 bootxx_cd9660 and the secondary bootstrap boot.pmax:
mkisofs -o /tmp/cd-image -a -l -v iso-source-dir ... 48 51 iso-source-dir/bootxx_cd9660 ... installboot -b $((48 * 4)) /tmp/cd-image /usr/mdec/bootxx_cd9660
Install the Berkeley Fast File System primary bootstrap on to disk
‘sd0
’, with the secondary bootstrap
/boot already present:
installboot /dev/rsd0c
/usr/mdec/bootxx /boot
Install the primary bootstrap on to disk
‘sd0
’:
installboot /dev/rsd0c
/usr/mdec/bootblk
The secondary NetBSD/sparc64 bootstrap is located in /usr/mdec/ofwboot.
Install the Berkeley Fast File System primary bootstrap on to disk
‘sd0
’, with the secondary bootstrap
/boot already present:
installboot /dev/rsd0c
/usr/mdec/bootxx /boot
Install the Berkeley Fast File System primary bootstrap on to disk
‘ra0
’:
installboot /dev/rra0c
/usr/mdec/raboot
The primary bootstrap works with FFSv1 and FFSv2 file systems. The secondary NetBSD/vax bootstrap is located in /usr/mdec/boot.
The installboot
utility exits 0 on
success, and >0 if an error occurs.
uname(3), boot(8), disklabel(8), dumpfs(8), fdisk(8), gpt(8), x86/mbr(8), x86/pxeboot(8)
This implementation of installboot
appeared in NetBSD 1.6.
The machine independent portion of this implementation of
installboot
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),
Michael Hitch (amiga), Paul
Kranenburg (sparc), David Laight (i386),
Christian Limpach (next68k), Luke
Mewburn (macppc), Matt Thomas (vax),
Izumi Tsutsui (news68k, newsmips), and
UCHIYAMA Yasushi (ews4800mips).
There are not currently primary bootstraps to support all file systems types which are capable of being the root file system.
If a disk has been converted from FFS to RAID without the contents
of the disk erased, then the original FFS installation may be auto-detected
instead of the RAID installation. In this case, the
-t
raid
option must be
provided.
The NetBSD/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.
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.
The disk must have a boot partition large enough to hold the bootstrap code. Currently the primary bootstrap must be a LIF format file.
The bootstrap must be installed in the
NetBSD partition that starts at the beginning of the
MBR partition. If that is a valid filesystem and contains the
/boot program then it will be used as the root
filesystem, otherwise the ‘a
’
partition will be booted.
The size of primary bootstrap programs is restricted to 8KB, even though some file systems (e.g., ISO 9660) are able to accommodate larger ones.
Due to restrictions in installboot
and the
secondary bootstrap implementation, file systems where kernels exist must
start at the beginning of disks.
Currently, installboot
doesn't recognize
an existing Apple partition map on the disk and always writes a faked map to
make disks bootable.
The NetBSD/macppc bootstrap program can't load kernels from FFSv2 partitions.
The size of bootstrap programs is restricted to the free space before the file system at the beginning of the disk minus 8KB.
The NetBSD/pmax secondary bootstrap program can only load kernels from file systems starting at the beginning of disks.
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.
The NetBSD/sun2 and NetBSD/sun3 secondary bootstrap program can only load kernels from file systems starting at the beginning of disks.
The NetBSD/vax secondary bootstrap program can only load kernels from file systems starting at the beginning of disks.
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.
December 29, 2024 | NetBSD 10.99 |