NAME
pxeboot —
network boot NetBSD/x86
through a PXE BIOS extension
DESCRIPTION
pxeboot is a
NetBSD boot program
running on top of a PXE BIOS extension which is provided by the motherboard or
a plug-in network adapter, in accordance with the Intel Preboot eXecution
Environement (PXE) specification.
By default, the
pxeboot program is configured with modules
loading and
boot.cfg(5)
support disabled. See
EXAMPLES for how to
enable these options individually. This manual page assumes that
boot.cfg(5) support is
enabled.
Network booting a system through PXE is a two-stage process:
- The PXE BIOS issues a DHCP request and fetches the
NetBSD pxeboot program using
TFTP.
- The NetBSD
pxeboot program takes control. It immediately issues
another DHCP request to get the name of a
boot.cfg(5) file to
load, using “boot.cfg” by default. If the boot config file is
not found, or if the supplied file appears not to be a boot configuration
file, the file is skipped. Otherwise it is loaded and obeyed as described
in boot.cfg(5). If a
boot configuration is not loaded, the user has the option to enter a
limited version of the standard interactive boot mode by pressing a key
within five seconds. After this time, or after the user's
boot command, another DHCP request is issued and the
kernel filename returned by the DHCP reply, using “netbsd” by
default, is loaded. To read the kernel file, the NFS (version 2) or TFTP
protocols can be used.
The DHCP request issued by the
NetBSD
pxeboot program has the following special parameters:
-
-
- Bootfile name
- is set to “boot.cfg” during the first request,
and then to the filename argument on the
boot command line typed in by the user (can be empty),
using “netbsd” in the non-interactive case.
-
-
- DHCP Vendor class identifier
tag
- is set to “NetBSD:i386:libsa”.
The DHCP server can use these fields (i.e. the DHCP vendor class identifier tag
and the requested file name, possibly supplied by the user's command line
input to the
pxeboot program) to distinguish between the
various originators of requests (PXE BIOS, first and second
pxeboot stage,
NetBSD kernel), and
to alter its behaviour. For example, this can be used to support alternative
NetBSD installations on one machine.
In addition to the standard network interface configuration, the following
fields in the DHCP reply are interpreted:
-
-
- Bootfile name
- specifies the protocol to be used, and the filename of the
boot config or NetBSD kernel to be booted,
separated by a colon. Available protocols are “nfs” and
“tftp”. The boot config or kernel filename part is interpreted
relatively to the NFS root directory (see the Root path
reply field below) or the TFTP server's root directory (which might be a
subdirectory within the TFTP server's filesystem, depending on the
implementation), respectively. If the Bootfile name
field replied by the DHCP server does not contain a colon, it is ignored,
and the filename typed in at the
pxeboot command line prompt (or the “netbsd”
default, see the section about the Bootfile name field
in the DHCP request above) is used. If no protocol was specified,
“nfs” is assumed.
-
-
- Next server
- is used as the location of the tftp server.
-
-
- Swap server
- can be used to override the “server IP address”
if NFS is used to access the kernel. This matches the behaviour of the
NetBSD kernel to access its root file system on
NFS. This way, different TFTP and NFS servers can be communicated to the
DHCP client (it is actually a deficiency of the DHCP protocol to provide a
“root path” field but no corresponding IP address).
-
-
- Root path
- is used as path to be mounted in the NFS case to access the
kernel file, matching the NetBSD kernel's
behaviour.
The commands accepted in interactive mode are:
-
-
- boot
[device:][filename]
[-1234abcdmqsvxz]
- Boot NetBSD. See
boot in
x86/boot(8) for full
details.
-
-
- help
- Print an overview about commands and arguments.
-
-
- quit
- Leave the pxeboot program.
By default the output from
pxeboot and from the booted kernel
will go to the system's BIOS console. This can be changed to be one of the
serial ports by using
installboot to modify the boot options
contained in the
pxeboot_ia32.bin file.
FILES
-
-
- /usr/mdec/pxeboot_ia32.bin
-
EXAMPLES
To enable
boot.cfg(5) support
in the
pxeboot program:
installboot -e -o bootconf pxeboot_ia32.bin
To enable modules loading support in the
pxeboot program:
installboot -e -o modules pxeboot_ia32.bin
The first
/etc/dhcpd.conf example shows a simple configuration
which just loads “boot.cfg” and “netbsd” from the
client's NFS root directory, using the defaults for protocol and kernel
filename. Similar setups should be possible with any BOOTP/DHCP server.
host myhost {
hardware ethernet 00:00:00:00:00:00;
fixed-address myhost;
option host-name "myhost";
filename "pxeboot_ia32.bin";
option swap-server mynfsserver;
option root-path "/export/myhost";
}
The following
/etc/dhcpd.conf entry sets loads the boot config
and kernel over tftp. This can be used, for example, for installing machines
by using an install kernel.
host myhost {
hardware ethernet 00:00:00:00:00:00;
fixed-address myhost;
option host-name "myhost";
next-server mytftpserver;
# This section allows dhcpd to respond with different answers
# for the different tftp requests for the bootloader and kernel.
if substring (option vendor-class-identifier, 0, 20)
= "PXEClient:Arch:00000" {
filename "pxeboot_ia32.bin";
} elsif substring (option vendor-class-identifier, 0, 17)
= "NetBSD:i386:libsa" {
if filename = "boot.cfg" {
filename "tftp:boot.cfg";
} else if filename = "netbsd" {
filename "tftp:netbsd-INSTALL.gz";
}
}
}
The following
/etc/dhcpd.conf entry shows how different system
installations can be booted depending on the user's input on the
pxeboot command line.
host myhost {
hardware ethernet 00:00:00:00:00:00;
fixed-address myhost;
option host-name "myhost";
next-server mytftpserver;
if substring (option vendor-class-identifier, 0, 9) = "PXEClient" {
filename "pxeboot_ia32.bin";
} elsif filename = "boot.cfg" {
filename "tftp:boot.cfg";
} elsif filename = "tftp" {
filename "tftp:netbsd.myhost";
} else {
option swap-server mynfsserver;
option root-path "/export/myhost";
if filename = "generic" {
filename "nfs:gennetbsd";
} else {
filename "nfs:netbsd";
}
}
}
The TFTP server is supplied using the
next-server directive.
The NFS server for the root file system is
mynfsserver. The
swap-server:root-path is only used in the NFS case and by
the
NetBSD kernel to mount the root file system.
SEE ALSO
boot.cfg(5),
dhcpd(8),
diskless(8),
installboot(8),
x86/boot(8)
Intel Corporation,
Preboot Execution Environment (PXE) Specification,
Version 2.1, September 20,
1999.
HISTORY
The
NetBSD/x86
pxeboot command first
appeared in
NetBSD 1.6.
BUGS
If an error is encountered while reading the
NetBSD
kernel file or if its file format wasn't recognized, it is impossible to retry
the operation because the PXE network stack is already removed from the system
RAM.
You need the
pxeboot from an i386 build to boot an i386
kernel, and that from an amd64 build to boot an amd64 kernel.
In a Xen setup, the
NetBSD DOM0 kernel is loaded as a
module, and cannot know the device from which the Xen hypervisor was booted.
In this case, the DOM0 kernel will fall back to the default boot device
(typically the first disk on the host). If the boot device is different from
the default one, consider passing additional arguments, like
bootdev, to the DOM0 kernel as explained in the
load command subsection in
x86/boot(8).