31.8.Â Diskless Operation with PXE

Updated by Jean-FranÃ§oisDockÃ¨s.

Reorganized and enhanced by AlexDupre.

The IntelÂ® Preboot eXecution Environment
(PXE) allows an operating system to boot over
the network. For example, a FreeBSD system can boot over the
network and operate without a local disk, using file systems
mounted from an NFS server.
PXE support is usually available in the
BIOS. To use PXE when the
machine starts, select the Boot from network
option in the BIOS setup or type a function
key during system initialization.

In order to provide the files needed for an operating system
to boot over the network, a PXE setup also
requires properly configured DHCP,
TFTP, and NFS servers,
where:

Initial parameters, such as an IP
address, executable boot filename and location, server name,
and root path are obtained from the
DHCP server.

The operating system loader file is booted using
TFTP.

The file systems are loaded using
NFS.

When a computer PXE boots, it receives
information over DHCP about where to obtain
the initial boot loader file. After the host computer receives
this information, it downloads the boot loader via
TFTP and then executes the boot loader. In
FreeBSD, the boot loader file is
/boot/pxeboot. After
/boot/pxeboot executes, the FreeBSD kernel is
loaded and the rest of the FreeBSD bootup sequence proceeds, as
described in ChapterÂ 12, The FreeBSD Booting Process.

This section describes how to configure these services on a
FreeBSD system so that other systems can PXE
boot into FreeBSD. Refer to diskless(8) for more
information.

Caution:

As described, the system providing these services is
insecure. It should live in a protected area of a network and
be untrusted by other hosts.

31.8.1.Â Setting Up the PXE
Environment

Written by CraigRodrigues.

The steps shown in this section configure the built-in
NFS and TFTP servers.
The next section demonstrates how to install and configure the
DHCP server. In this example, the
directory which will contain the files used by
PXE users is
/b/tftpboot/FreeBSD/install. It is
important that this directory exists and that the same
directory name is set in both
/etc/inetd.conf and
/usr/local/etc/dhcpd.conf.

Create the root directory which will contain a FreeBSD
installation to be NFS mounted:

#export NFSROOTDIR=/b/tftpboot/FreeBSD/install#mkdir -p ${NFSROOTDIR}

Enable the NFS server by adding
this line to /etc/rc.conf:

nfs_server_enable="YES"

Export the diskless root directory via
NFS by adding the following to
/etc/exports:

Note:

Install the base system into
${NFSROOTDIR}, either by
decompressing the official archives or by rebuilding
the FreeBSD kernel and userland (refer to
SectionÂ 23.5, “Updating FreeBSD from Source” for more detailed
instructions, but do not forget to add
DESTDIR=${NFSROOTDIR}
when running the
make installkernel and
make installworld commands.

Test that the TFTP server works and
can download the boot loader which will be obtained via
PXE:

Replace myhost.example.com
with the hostname or IP address of the
NFS server. In this example, the root
file system is mounted read-only in order to prevent
NFS clients from potentially deleting
the contents of the root file system.

Set the root password in the PXE
environment for client machines which are
PXE booting :

#chroot ${NFSROOTDIR}#passwd

If needed, enable ssh(1) root logins for client
machines which are PXE booting by
editing
${NFSROOTDIR}/etc/ssh/sshd_config and
enabling PermitRootLogin. This option
is documented in sshd_config(5).

Perform any other needed customizations of the
PXE environment in
${NFSROOTDIR}. These customizations
could include things like installing packages or editing
the password file with vipw(8).

When booting from an NFS root volume,
/etc/rc detects the
NFS boot and runs
/etc/rc.initdiskless. In this case,
/etc and /var need
to be memory backed file systems so that these directories are
writable but the NFS root directory is
read-only:

When the system boots, memory file systems for
/etc and /var will
be created and mounted and the contents of the
cpio.gz files will be copied into
them. By default, these file systems have a maximum capacity
of 5 megabytes. If your archives do not fit, which is
usually the case for /var when binary
packages have been installed, request a larger size by putting
the number of 512 byte sectors needed (e.g., 5 megabytes
is 10240 sectors) in
${NFSROOTDIR}/conf/base/etc/md_size and
${NFSROOTDIR}/conf/base/var/md_size
files for /etc and
/var file systems respectively.

31.8.2.Â Configuring the DHCP Server

The DHCP server does not need to be the
same machine as the TFTP and
NFS server, but it needs to be accessible
in the network.

DHCP is not part of the FreeBSD base
system but can be installed using the
net/isc-dhcp43-server port or
package.

Once installed, edit the configuration file,
/usr/local/etc/dhcpd.conf. Configure
the next-server,
filename, and
root-path settings as seen in this
example:

The next-server directive is used to
specify the IP address of the
TFTP server.

The filename directive defines the path
to /boot/pxeboot. A relative filename is
used, meaning that /b/tftpboot is not
included in the path.

The root-path option defines the path
to the NFS root file system.

Once the edits are saved, enable DHCP
at boot time by adding the following line to
/etc/rc.conf:

dhcpd_enable="YES"

Then start the DHCP service:

#service isc-dhcpd start

31.8.3.Â Debugging PXE Problems

Once all of the services are configured and started,
PXE clients should be able to
automatically load FreeBSD over the network. If a particular
client is unable to connect, when that client machine boots
up, enter the BIOS configuration menu and
confirm that it is set to boot from the network.

This section describes some troubleshooting tips for
isolating the source of the configuration problem should no
clients be able to PXE boot.

Use the net/wireshark package or
port to debug the network traffic involved during the
PXE booting process, which is
illustrated in the diagram below.

FigureÂ 31.1.Â PXE Booting Process with
NFS Root Mount

Client broadcasts a
DHCPDISCOVER message.

The DHCP server responds
with the IP address,
next-server,
filename, and
root-path values.

The client sends a TFTP
request to next-server,
asking to retrieve
filename.

The TFTP server responds
and sends filename to
client.

The client executes
filename, which is
pxeboot(8), which then loads the kernel.
When the kernel executes, the root file system
specified by root-path is
mounted over NFS.

On the
TFTP server, read
/var/log/xferlog to ensure that
pxeboot is being retrieved from
the correct location. To test this example
configuration: