diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index ac3bbb8962..81f0414593 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -2395,6 +2395,13 @@ Exports list on foobar:
Updated by
+
+
+ Alex
+ Dupre
+ Reorganized and enhanced by
+
+
Diskless Operation
@@ -2402,9 +2409,9 @@ Exports list on foobar:
diskless operation
A FreeBSD machine can boot over the network and operate without a
- local disk, using filesystems mounted from an NFS server. No system
+ local disk, using filesystems mounted from an NFS server. No system
modification is necessary, beyond standard configuration files.
- Such a system is easy to set up because all the necessary elements
+ Such a system is relatively easy to set up because all the necessary elements
are readily available:
@@ -2444,14 +2451,14 @@ Exports list on foobar:
- Swapping, if needed, can be done either to an NFS file or to
+ Swapping, if needed, can be done either to an NFS file or to
a local disk.
There are many ways to set up diskless workstations. Many
elements are involved, and most can be customized to suit local
- taste. The following will describe the setup of a complete system,
+ taste. The following will describe variations on the setup of a complete system,
emphasizing simplicity and compatibility with the
standard FreeBSD startup scripts. The system described has the
following characteristics:
@@ -2466,12 +2473,13 @@ Exports list on foobar:
configuration files overridden by ones specific to diskless
operation or, possibly, to the workstation they belong to.
The parts of the root which have to be
- writable are overlaid with &man.mfs.8; filesystems. Any changes
+ writable are overlaid with &man.mfs.8; (&os; 4.X) or &man.md.4; (&os; 5.X) filesystems. Any changes
will be lost when the system reboots.
- The kernel is loaded by etherboot
- , using DHCP (or BOOTP) and TFTP.
+ The kernel is transferred and loaded either with
+ etherboot or PXE
+ as some situations may mandate the use of either method.
@@ -2480,63 +2488,138 @@ Exports list on foobar:
other hosts.
+ All the information in this section has been tested
+ using &os; releases 4.9-RELEASE and 5.2.1-RELEASE. The text is
+ primarily structured for 4.X usage. Notes have been inserted where
+ appropriate to indicate 5.X changes.
+
+
+ Background Information
+
+ Setting up diskless workstations is both relatively
+ straightforward and prone to errors. These are sometimes
+ difficult to diagnose for a number of reasons. For example:
+
+
+
+ Compile time options may determine different behaviours at
+ runtime.
+
+
+
+ Error messages are often cryptic or totally absent.
+
+
+
+ In this context, having some knowledge of the background
+ mechanisms involved is very useful to solve the problems that
+ may arise.
+
+ Several operations need to be performed for a successful
+ bootstrap:
+
+
+
+ The machine needs to obtain initial parameters such as its IP
+ address, executable filename, server name, root path. This is
+ done using the DHCP or BOOTP protocols.
+ DHCP is a compatible extension of BOOTP, and
+ uses the same port numbers and basic packet format.
+
+ It is possible to configure a system to use only BOOTP.
+ The &man.bootpd.8; server program is included in the base &os;
+ system.
+
+ However, DHCP has a number of advantages
+ over BOOTP (nicer configuration files, possibility of using
+ PXE, plus many others not directly related to
+ diskless operation), and we will describe mainly a
+ DHCP configuration, with equivalent exemples
+ using &man.bootpd.8; when possible. The sample configuration will
+ use the ISC DHCP software package
+ (release 3.0.1.r12 was installed on the test server).
+
+
+
+ The machine needs to transfer one or several programs to local
+ memory. Either TFTP or NFS
+ are used. The choice between TFTP and
+ NFS is a compile time option in several places.
+ A common source of error is to specify filenames for the wrong
+ protocol: TFTP typically transfers all files from
+ a single directory on the server, and would expect filenames
+ relative to this directory. NFS needs absolute
+ file paths.
+
+
+
+ The possible intermediate bootstrap programs and the kernel
+ need to be initialized and executed. There are several important
+ variations in this area:
+
+
+
+ PXE will load &man.pxeboot.8;, which is
+ a modified version of the &os; third stage loader. The
+ &man.loader.8; will obtain most parameters necessary to system
+ startup, and leave them in the kernel environment before
+ transferring control. It is possible to use a
+ GENERIC kernel in this case.
+
+
+
+ etherboot, will directly
+ load the kernel, with less preparation. You will need to
+ build a kernel with specific options.
+
+
+
+ PXE and etherboot
+ work equally well with 4.X systems. Because 5.X kernels
+ normally let the &man.loader.8; do more work for them,
+ PXE is preferred for 5.X systems.
+
+ If your BIOS and network cards support
+ PXE, you should probably use it. However,
+ it is still possible to start a 5.X system with
+ etherboot.
+
+
+
+ Finally, the machine needs to access its filesystems.
+ NFS is used in all cases.
+
+
+
+ See also &man.diskless.8; manual page.
+
Setup Instructions
- Configuring DHCP/BOOTP
-
- diskless operation
- booting
-
-
- There are two protocols that are commonly used to boot a
- workstation that retrieves its configuration over the network: BOOTP
- and DHCP. They are used at several points in the workstation
- bootstrap:
-
- etherboot uses
- DHCP (by default) or BOOTP (needs a configuration option) to
- find the kernel. (PXE uses DHCP).
-
- The kernel uses BOOTP to locate the NFS
- root.
-
-
-
- It is possible to configure a system to use only BOOTP.
- The &man.bootpd.8; server program is included in the
- base FreeBSD system.
-
- However, DHCP has a number of advantages over BOOTP (nicer
- configuration files, possibility of using PXE, plus many others
- not directly related to diskless operation), and we shall describe
- both a pure BOOTP, and a BOOTP+DHCP configuration, with an
- emphasis on the latter, which will use the ISC DHCP software
- package.
-
-
- Configuration Using ISC DHCP
+ Configuration Using <application>ISC DHCP</application>
DHCP
diskless operation
- The isc-dhcp server can answer
- both BOOTP and DHCP requests.
+ The ISC DHCP server can answer
+ both BOOTP and DHCP requests.
- As of release 4.4, isc-dhcp
+ As of release 4.9, ISC DHCP
3.0 is not part of the base
system. You will first need to install the
net/isc-dhcp3-server port or the
corresponding package. Please refer to
for general information about ports and packages.
- Once isc-dhcp is installed, it
+ Once ISC DHCP is installed, it
needs a configuration file to run, (normally named
/usr/local/etc/dhcpd.conf). Here follows
- a commented example:
+ a commented example, where host margaux
+ uses etherboot and host
+ corbieres uses PXE:
default-lease-time 600;
@@ -2555,16 +2638,23 @@ Exports list on foobar:
host margaux {
hardware ethernet 01:23:45:67:89:ab;
fixed-address margaux.example.com;
- next-server 192.168.4.4;
- filename "/tftpboot/kernel.diskless";
- option root-path "192.168.4.4:/data/misc/diskless";
+ next-server 192.168.4.4;
+ filename "/data/misc/kernel.diskless";
+ option root-path "192.168.4.4:/data/misc/diskless";
+ }
+ host corbieres {
+ hardware ethernet 00:02:b3:27:62:df;
+ fixed-address corbieres.example.com;
+ next-server 192.168.4.4;
+ filename "pxeboot";
+ option root-path "192.168.4.4:/data/misc/diskless";
}
}
This option tells
- dhcpd to send the value in the
+ dhcpd to send the value in the
host declarations as the hostname for the
diskless host. An alternate way would be to add an
option host-name
@@ -2574,44 +2664,59 @@ Exports list on foobar:
The
next-server directive designates
- the TFTP server (the default is to use the same host as the
- DHCP server).
+ the TFTP or NFS server to
+ use for loading loader or kernel file (the default is to use
+ the same host as the
+ DHCP server).
The
filename directive defines the file that
- etherboot will load as a
- kernel.
- PXE appears to prefer a relative file
- name, and it loads pxeboot, not the
- kernel (option filename
- "pxeboot").
-
-
+ etherboot or PXE
+ will load for the next execution step. It must be specified
+ according to the transfer method used.
+ etherboot can be compiled to use
+ NFS or TFTP. The &os;
+ port configures NFS by default.
+ PXE uses TFTP, which is
+ why a relative filename is used here (this may depend on the
+ TFTP server configuration, but would be
+ fairly typical). Also, PXE loads
+ pxeboot, not the kernel. There are other
+ interesting possibilities, like loading
+ pxeboot from a &os; CD-ROM
+ /boot directory (as
+ &man.pxeboot.8; can load a GENERIC kernel,
+ this makes it possible to use PXE to boot
+ from a remote CD-ROM).
The
root-path option defines the path to
- the root filesystem, in usual NFS notation.
+ the root filesystem, in usual NFS notation.
+ When using PXE, it is possible to leave off
+ the host's IP as long as you do not enable the kernel option
+ BOOTP. The NFS server will then be
+ the same as the TFTP one.
-
-
+
+
Configuration Using BOOTP
BOOTP
diskless operation
- Here follows an equivalent bootpd
- configuration. This would be found in
+ Here follows an equivalent bootpd
+ configuration (reduced to one client). This would be found in
/etc/bootptab.
Please note that etherboot
must be compiled with the non-default option
NO_DHCP_SUPPORT in order to use BOOTP,
- and that PXE needs DHCP. The only
+ and that PXE needs DHCP. The only
obvious advantage of bootpd is
that it exists in the base system.
@@ -2627,7 +2732,6 @@ Exports list on foobar:
margaux:ha=0123456789ab:tc=.def100
-
@@ -2656,8 +2760,14 @@ Exports list on foobar:
of everything. Else refer to for
information about ports and packages.
+ You can change the etherboot
+ configuration (i.e. to use TFTP instead of
+ NFS) by editing the Config
+ file in the etherboot source
+ directory.
+
For our setup, we shall use a boot floppy. For other methods
- (PROM, or dos program), please refer to the
+ (PROM, or &ms-dos; program), please refer to the
etherboot documentation.
To make a boot floppy, insert a floppy in the drive on the
@@ -2677,9 +2787,32 @@ Exports list on foobar:
+
+ Booting with <acronym>PXE</acronym>
+
+ By default, the &man.pxeboot.8; loader loads the kernel via
+ NFS. It can be compiled to use
+ TFTP instead by specifying the
+ LOADER_TFTP_SUPPORT option in
+ /etc/make.conf. See the comments in
+ /etc/defaults/make.conf (or
+ /usr/share/examples/etc/make.conf for 5.X
+ systems) for instructions.
+
+ There are two other undocumented make.conf
+ options which may be useful for setting up a serial console diskless
+ machine: BOOT_PXELDR_PROBE_KEYBOARD, and
+ BOOT_PXELDR_ALWAYS_SERIAL (the latter only exists
+ on &os; 5.X).
+
+ To use PXE when the machine starts, you will
+ usually need to select the Boot from network
+ option in your BIOS setup, or type a function key
+ during the PC initialization.
+
- Configuring the TFTP and NFS Servers
+ Configuring the <acronym>TFTP</acronym> and <acronym>NFS</acronym> Servers
TFTP
@@ -2690,11 +2823,13 @@ Exports list on foobar:
diskless operation
- You need to enable tftpd on the TFTP
- server:
+ If you are using PXE or
+ etherboot configured to use
+ TFTP, you need to enable
+ tftpd on the file server:
- Create a directory from which tftpd
+ Create a directory from which tftpd
will serve the files, e.g. /tftpboot.
@@ -2702,16 +2837,16 @@ Exports list on foobar:
Add this line to your
/etc/inetd.conf:
- tftp dgram udp wait root /usr/libexec/tftpd tftpd -s /tftpboot
+ tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot
- It appears that at least some PXE versions want
- the TCP version of TFTP. In this case, add a second line,
+ It appears that at least some PXE versions want
+ the TCP version of TFTP. In this case, add a second line,
replacing dgram udp with stream
tcp.
- Tell inetd to reread its configuration
+ Tell inetd to reread its configuration
file:
&prompt.root; kill -HUP `cat /var/run/inetd.pid`
@@ -2722,8 +2857,8 @@ Exports list on foobar:
location is set in both inetd.conf and
dhcpd.conf.
- You also need to enable NFS and export the
- appropriate filesystem on the NFS server.
+ In all cases, you also need to enable NFS and export the
+ appropriate filesystem on the NFS server.
@@ -2735,14 +2870,14 @@ Exports list on foobar:
Export the filesystem where the diskless root directory
is located by adding the following to
/etc/exports (adjust the volume mount
- point and replace margaux
- with the name of the diskless workstation):
+ point and replace margaux corbieres
+ with the names of the diskless workstations):
- /data/misc -alldirs -ro margaux
+ /data/misc -alldirs -ro margaux corbieres
- Tell mountd to reread its configuration
- file. If you actually needed to enable NFS in
+ Tell mountd to reread its configuration
+ file. If you actually needed to enable NFS in
/etc/rc.conf
at the first step, you probably want to reboot instead.
&prompt.root; kill -HUP `cat /var/run/mountd.pid`
@@ -2759,23 +2894,50 @@ Exports list on foobar:
kernel configuration
- Create a kernel configuration file for the diskless client
- with the following options (in addition to the usual
- ones):
+ If using etherboot, you need to
+ create a kernel configuration file for the diskless client
+ with the following options (in addition to the usual ones):
options BOOTP # Use BOOTP to obtain IP address/hostname
options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info
- options BOOTP_COMPAT # Workaround for broken bootp daemons.
- You may also want to use BOOTP_NFSV3 and
- BOOTP_WIRED_TO (refer to LINT).
+ You may also want to use BOOTP_NFSV3,
+ BOOT_COMPAT and BOOTP_WIRED_TO
+ (refer to LINT in 4.X or
+ NOTES on 5.X).
- Build the kernel (See ),
- and copy it to the tftp directory, under the name listed
+ These option names are historical and slightly misleading as
+ they actually enable indifferent use of DHCP and
+ BOOTP inside the kernel (it is also possible to force strict BOOTP
+ or DHCP use).
+
+ Build the kernel (see ),
+ and copy it to the place specified
in dhcpd.conf.
+
+ When using PXE, building a kernel with the
+ above options is not strictly necessary (though suggested).
+ Enabling them will cause more DHCP requests to be
+ issued during kernel startup, with a small risk of inconsistency
+ between the new values and those retrieved by &man.pxeboot.8; in some
+ special cases. The advantage of using them is that the host name
+ will be set as a side effect. Otherwise you will need to set the
+ host name by another method, for example in a client-specific
+ rc.conf file.
+
+
+
+ In order to be loadable with
+ etherboot, a 5.X kernel needs to have
+ the device hints compiled in. You would typically set the
+ following option in the configuration file (see the
+ NOTES configuration comments file):
+
+ hints "GENERIC.hints"
+
@@ -2790,11 +2952,17 @@ Exports list on foobar:
You need to create a root filesystem for the diskless
workstations, in the location listed as
root-path in
- dhcpd.conf.
+ dhcpd.conf. The following sections describe
+ two ways to do it.
- The easiest way to do this is to use the
+
+ Using the <filename>clone_root</filename> Script
+
+ This is the quickest way to create a root filesystem, but
+ currently it is only supported on &os; 4.X. This shell script
+ is located at
/usr/share/examples/diskless/clone_root
- shell script. This script needs customization, at least to adjust
+ and needs customization, at least to adjust
the place where the filesystem will be created (the
DEST variable).
@@ -2812,21 +2980,51 @@ Exports list on foobar:
other examples in the diskless directory,
they actually document a configuration method which is distinct
from the one used by clone_root and
- /etc/rc.diskless[12], which is a little
- confusing. Use them for reference only, except if you prefer
+ the system startup scripts in
+ /etc, which is a little
+ confusing. Use them for reference only, except if you prefer
the method that they describe, in which case you will need
customized rc scripts.
+
+
+
+ Using the Standard <command>make world</command>
+ Procedure
+
+ This method can be applied to either &os; 4.X or 5.X and
+ will install a complete virgin system (not only the root filesystem)
+ into DESTDIR.
+ All you have to do is simply execute the following script:
+
+ #!/bin/sh
+export DESTDIR=/data/misc/diskless
+mkdir -p ${DESTDIR}
+cd /usr/src; make world && make kernel
+cd /usr/src/etc; make distribution
+
+ Once done, you may need to customize your
+ /etc/rc.conf and
+ /etc/fstab placed into
+ DESTDIR according to your needs.
+
Configuring Swap
If needed, a swap file located on the server can be
- accessed via NFS. The exact bootptab
- or dhcpd.conf options are not clearly
- documented at this time. The following configuration
- suggestions have been reported to work in some installations
- using isc-dhcp 3.0rc11.
+ accessed via NFS. One of the methods commonly
+ used to do this has been discontinued in release 5.X.
+
+
+ <acronym>NFS</acronym> Swap with &os; 4.X
+
+ The swap file location and size can be specified with
+ BOOTP/DHCP &os;-specific options 128 and 129.
+ Examples of configuration files for
+ ISC DHCP 3.0 or
+ bootpd follow:
+
Add the following lines to
dhcpd.conf:
@@ -2841,24 +3039,25 @@ Exports list on foobar:
option swap-size 64000;
}
- The idea is that, at least for a FreeBSD client,
- DHCP/BOOTP option code 128 is the path to the NFS swap file,
- and option code 129 is the swap size in kilobytes. Older
- versions of dhcpd allowed a syntax of
+
+ swap-path is the path to a directory
+ where swap files will be located. Each file will be named
+ swap.client-ip.
+
+ Older versions of dhcpd used a syntax of
option option-128 "..., which is no
longer supported.
/etc/bootptab would use the
following syntax instead:
- T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00
-
+ T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00
In /etc/bootptab, the swap
size must be expressed in hexadecimal format.
- On the NFS swap file server, create the swap
+ On the NFS swap file server, create the swap
file(s)
&prompt.root; mkdir /netswapvolume/netswap
@@ -2871,16 +3070,33 @@ Exports list on foobar:
- On the NFS swap file server, add the following line to
+ On the NFS swap file server, add the following line to
/etc/exports:
- /netswapvolume -maproot=0:10 -alldirs margaux
+ /netswapvolume -maproot=0:10 -alldirs margaux corbieres
Then tell mountd to reread the
exports file, as above.
+
+
+ <acronym>NFS</acronym> Swap with &os 5.X
+
+ The kernel does not support enabling NFS
+ swap at boot time. Swap must be enabled by the startup scripts,
+ by mounting a writeable file system and creating and enabling a
+ swap file. To create a swap file of appropriate size, you can do
+ like this:
+
+ &prompt.root; dd if=/dev/zero of=/path/to/swapfile bs=1k count=1 oseek=100000
+
+ To enable it you have to add the following line to your
+ rc.conf:
+
+ swapfile=/path/to/swapfile
+
@@ -2915,7 +3131,7 @@ Exports list on foobar:
to create the correct device entries (FreeBSD 5.0 and later
use &man.devfs.5; to allocate device nodes transparently for
the user, running MAKEDEV on these
- versions is useless).
+ versions is pointless).