INSTALLBOOT(8) | System Manager's Manual | INSTALLBOOT(8) |
installboot
—
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 |
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.
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.
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.
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).
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 precendence.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
installboot
.-b
s1bno option.installboot
is run.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.
Note that installboot
does not
currently support evbmips directly.
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
netbsd -ASn2
’ to
‘netbsd -S
’:
installboot -m amiga -o command="netbsd -S" /dev/rsd0a \ /usr/mdec/bootxx_ffsv1
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
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.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
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.
sd0
’:
installboot /dev/rsd0c
/usr/mdec/boot
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
sd0
’, with the secondary bootstrap
/boot already present:
installboot /dev/rsd0c
/usr/mdec/bootxx /boot
sd0
’:
installboot /dev/rsd0c
/usr/mdec/bootblk
The secondary NetBSD/sparc64 bootstrap is located in /usr/mdec/ofwboot.
sd0
’, with the secondary bootstrap
/boot already present:
installboot /dev/rsd0c
/usr/mdec/bootxx /boot
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.
installboot
utility exits 0 on success,
and >0 if an error occurs.
installboot
appeared in
NetBSD 1.6.
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).
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 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.
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.
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 primary bootstrap programs is restricted to 7.5KB, even though some file systems (e.g., ISO 9660) are able to accommodate larger ones.
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.
May 19, 2024 | NetBSD 10.1 |