Updated by Luigi Rizzo
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$FreeBSD: head/share/man/man8/diskless.8 108228 2002-12-23 18:44:22Z dillon $
.Dd April 18, 2001 .Dt DISKLESS 8 .Os .Sh NAME .Nm diskless .Nd booting a system over the network .Sh DESCRIPTION The ability to boot a machine over the network is useful for .Em diskless or .Em dataless machines, or as a temporary measure while repairing or re-installing filesystems on a local disk. This file provides a general description of the interactions between a client and its server when a client is booting over the network. .Sh OPERATION When booting a system over the network, there are three phases of interaction between client and server:
p l -enum -compact t The stage-1 bootstrap, typically PXE built into your ethernet card, loads a second-stage boot program. t The second-stage boot program, typically 'pxeboot', loads modules and the kernel and boots the kernel. t The kernel NFS mounts the root directory and continues from there. .El
p Each of these phases are described in further detail below.
p First the stage-1 bootstrap loads the stage-2 boot program over the network. The stage-1 bootstrap typically uses BOOTP or DHCP to obtain the filename to load, then uses TFTP to load the file. This file is typically called "pxeboot" and should be copied from
a /boot/pxeboot into the tftp directory on the server, which is typically
a /tftpdir .
p The stage-2 boot program then loads additional modules and the kernel. These files may not exist on the DHCP or BOOTP server. You can use the .Sy next-server option available in DHCP configurations to specify the server holding the second stage boot files and kernel. The stage-2 program uses NFS or TFTP to obtain these files. By default, NFS is used. If you are using pxeboot you can install a version that uses TFTP by setting LOADER_TFTP_SUPPORT=YES in your
a /etc/make.conf , then recompiling and reinstalling pxeboot via the command listed below. It is often necessary to use TFTP here so you can place a custom kernel in /tftpdir/. If you use NFS and do not have a custom root filesystem for the diskless client, the stage-2 boot will load your server's kernel as the kernel for the diskless machine, which may not be what you want to have happen. d -literal -offset indent cd /usr/src/sys/i386/boot make clean; make; make install cp /boot/pxeboot /tftpdir/ .Ed
p In phase 3, the kernel again uses DHCP or BOOTP to acquire configuration information, and proceeds to mount the root filesystem and start operation. The boot scripts recognize a diskless startup and peform the actions found in
a /etc/rc.d/initdiskless and
a /etc/rc.d/diskless . In older systems the scripts are located in
a /etc/rc.diskless1 and
a /etc/rc.diskless2 . .Sh CONFIGURATION In order to run a diskless client, you need the following: l -bullet t An NFS server which exports a root and /usr partition with appropriate permissions. The diskless scripts work with readonly partitions, as long as root is exported with .Fl maproot Ns =0 so that some system files can be accessed. As an example,
a /etc/exports can contain the following lines: d -literal -offset indent <ROOT> -ro -maproot=0 -alldirs <list of diskless clients> /usr -ro -alldirs <list of diskless clients> .Ed
p where .Aq ROOT is the mountpoint on the server of the root partition. The script
a /usr/share/examples/diskless/clone_root can be used to create a shared readonly root partition, but in many cases you may decide to export (again as readonly) the root directory used by the server itself. t a .Tn BOOTP or .Tn DHCP server. .Xr bootpd 8 can be enabled by uncommenting the .Em bootps line in
a /etc/inetd.conf . A sample
a /etc/bootptab can be the following: d -literal -offset indent .default:\\ hn:ht=1:vm=rfc1048:\\ :sm=255.255.255.0:\\ :sa=<SERVER>:\\ :gw=<GATEWAY>:\\ :rp="<SERVER>:<ROOT>": <CLIENT>:ha=0123456789ab:tc=.default .Ed
p where .Aq SERVER , .Aq GATEWAY and .Aq ROOT have the obvious meanings. t A properly initialized root partition. The script
a /usr/share/examples/diskless/clone_root can help in creating it, using the server's root partition as a reference. If you are just starting out you should simply use the server's own root directory,
a / , and not try to clone it.
p You often do not want to use the same
a rc.conf or
a rc.local files for the diskless boot as you do on the server. The diskless boot scripts provide a mechanism through which you can override various files in
a /etc (as well as other subdirectories of root). The scripts provide four overriding directories situated in
a /conf/<broadcast-ip> , and
a /conf/<machine-ip> . You should always create
a /conf/base/etc , which will entirely replace the server's
a /etc on the diskless machine. You can clone the server's
a /etc here or you can create a special file which tells the diskless boot scripts to remount the server's
a /etc onto
a /conf/base/etc . You do this by creating the file
a /conf/base/etc/diskless_remount containing the mount point to use as a basis of the diskless machine's
a /etc . For example, the file might contain: d -literal -offset 4n 10.0.0.1:/etc .Ed
p The diskless scripts create memory filesystems to hold the overriden directories. Only a 2MB partition is created by default, which may not be sufficient for your purposes. To override this you can create the file
a /conf/base/etc/md_size containing the size, in 512 byte sectors, of the memory disk to create for that directory.
p You then typically provide file-by-file overrides in the
a /conf/default/etc directory. At a minimum you must provides overrides for
a /conf/default/etc/rc.conf , and
a /conf/default/etc/rc.local .
p Overrides are hierarchical. You can supply network-specific defaults in the
a /conf/<BROADCASTIP>/etc directory, where <BROADCASTIP> represents the broadcast IP address of the diskless system as given to it via .Tn BOOTP . The
a diskless_remount and
a md_size features work in any of these directories. The configuration feature works on directories other then
a /etc , you simply create the directory you wish to replace or override in
a /conf/{base,default,<broadcast>,<ip>}/* and work it in the same way that you work
a /etc .
p Since you normally clone the server's
a /etc using the
a /conf/base/etc/diskless_remount , you might wish to remove unneeded files from the memory filesystem. For example, if the server has a firewall but you do not, you might wish to remove
a /etc/ipfw.conf . You can do this by creating a
a /conf/base/<DIRECTORY>.remove file. For example,
a /conf/base/etc.remove , which contains a list of relative paths that the boot scripts should remove from the memory file systems.
p As a minimum, you normally need to have the following in
a /conf/default/etc/fstab d -literal -offset indent <SERVER>:<ROOT> / nfs ro 0 0 <SERVER>:/usr /usr nfs ro 0 0 proc /proc procfs rw 0 0 .Ed
p You also need to create a customized version of
a /conf/default/etc/rc.conf which should contain the startup options for the diskless client, and
a /conf/default/etc/rc.local which could be empty but prevents the server's own
a /etc/rc.local from leaking onto the diskless system.
p In
a rc.conf , most likely you will not need to set .Va hostname and .Va ifconfig_* because these will be already set by the startup code. Finally, it might be convenient to use a c case statement using .Li `hostname` as the switch variable to do machine-specific configuration in case a number of diskless clients share the same configuration files. t The kernel for the diskless clients, which will be loaded using NFS or TFTP, should be built with at least the following options: d -literal -offset indent options BOOTP options BOOTP_NFSROOT options BOOTP_COMPAT .Ed
p In the devices section add: d -literal -offset indent device md .Ed
p If you use the firewall, remember to default to open or your kernel will not be able to send/receive the bootp packets. .El .Sh SECURITY ISSUES Be warned that using unencrypted NFS to mount root and user partitions may expose information such as encryption keys. .Sh BUGS This manpage is probably incomplete.
p .Fx sometimes requires to write onto the root partition, so the startup scripts mount MFS filesystems on some locations (e.g.\&
a /etc and
a /var ) , while trying to preserve the original content. The process might not handle all cases. .Sh SEE ALSO .Xr ethers 5 , .Xr exports 5 , .Xr bootpd 8 , .Xr mountd 8 , .Xr nfsd 8 , .Xr pxeboot 8 , .Xr reboot 8 , .Xr tftpd 8 , .Xr ports/net/etherboot