Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DISKLESS(8)		FreeBSD	System Manager's Manual		   DISKLESS(8)

     diskless -- booting a system over the network

     The ability to boot a machine over	the network is useful for diskless or
     dataless machines,	or as a	temporary measure while	repairing or re-in-
     stalling file systems on a	local disk.  This file provides	a general de-
     scription of the interactions between a client and	its server when	a
     client is booting over the	network.

     When booting a system over	the network, there are three phases of inter-
     action between client and server:

     1.	  The stage-1 bootstrap, typically PXE built into your Ethernet	card,
	  loads	a second-stage boot program.

     2.	  The second-stage boot	program, typically pxeboot(8), loads modules
	  and the kernel, and boots the	kernel.

     3.	  The kernel NFS mounts	the root directory and continues from there.

     Each of these phases are described	in further detail below.

     First, the	stage-1	bootstrap loads	the stage-2 boot program over the net-
     work.  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 typi-
     cally called pxeboot, and should be copied	from /boot/pxeboot into	the
     TFTP directory on the server, which is typically /tftpdir.

     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
     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(8), you can install a version that uses TFTP	by setting
     LOADER_TFTP_SUPPORT=YES in	your make.conf(5), then	recompiling and	rein-
     stalling pxeboot(8) 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 file	system 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.

	   cd /usr/src/stand
	   make	clean; make; make install
	   cp /boot/pxeboot /tftpdir/

     In	phase 3, the kernel acquires IP	networking configuration in one	of two
     ways, and then proceeds to	mount the root file system and start opera-
     tion.  If the phase 2 loader supports passing network configuration to
     the kernel	using the kernel environment, then the kernel will configure
     the network interface using that information.  Otherwise, it must use
     DHCP or BOOTP to acquire configuration information.  The boot scripts
     recognize a diskless startup and perform the actions found	in
     /etc/rc.d/resolv, /etc/rc.d/tmp, /etc/rc.d/var, and /etc/rc.initdiskless.

     In	order to run a diskless	client,	you need the following:

     o	 An NFS	server which exports a root and	/usr partitions	with appropri-
	 ate permissions.  The diskless	scripts	work with read-only parti-
	 tions,	as long	as root	is exported with -maproot=0 so that some sys-
	 tem files can be accessed.  As	an example, /etc/exports can contain
	 the following lines:

	       <ROOT> -ro -maproot=0 -alldirs <list of diskless	clients>
	       /usr -ro	-alldirs <list of diskless clients>

	 where <ROOT> is the mount point on the	server of the root partition.
	 The script /usr/share/examples/diskless/clone_root can	be used	to
	 create	a shared read-only root	partition, but in many cases you may
	 decide	to export (again as read-only) the root	directory used by the
	 server	itself.

     o	 A BOOTP or DHCP server.  bootpd(8) can	be enabled by uncommenting the
	 "bootps" line in /etc/inetd.conf.  A sample /etc/bootptab can be the



	 where <SERVER>, <GATEWAY> and <ROOT> have the obvious meanings.

     o	 A properly initialized	root partition.	 The script
	 /usr/share/examples/diskless/clone_root can help in creating it, us-
	 ing the server's root partition as a reference.  If you are just
	 starting out, you should simply use the server's own root directory,
	 /, and	not try	to clone it.

	 You often do not want to use the same rc.conf or 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
	 /etc (as well as other	subdirectories of root).

	 One difference	that you should	pay particular attention to is the
	 value of local_startup	in /etc/defaults/rc.conf.  A typical value for
	 a diskless boot is mountcritremote, however your needs	may be differ-

	 The scripts provide four overriding directories situated in
	 /conf/base, /conf/default, /conf/_broadcast-ip_, and
	 /conf/_machine-ip_.  You should always	create /conf/base/etc, which
	 will entirely replace the server's /etc on the	diskless machine.  You
	 can clone the server's	/etc here or you can create a special file
	 which tells the diskless boot scripts to remount the server's /etc
	 onto /conf/base/etc.  You do this by creating the file
	 /conf/base/etc/diskless_remount containing the	mount point to use as
	 a basis of the	diskless machine's /etc.  For example, the file	might

	 Alternatively,	if the server contains several independent roots, the
	 file might contain:

	 This would work, but if you copied /usr/diskless/4.7-RELEASE to
	 /usr/diskless/4.8-RELEASE and upgraded	the installation, you would
	 need to modify	the diskless_remount files to reflect that move.  To
	 avoid that, paths in diskless_remount files beginning with / have the
	 actual	path of	the client's root prepended to them so the file	could
	 instead contain:


	 The diskless scripts create memory file systems to hold the overrid-
	 den directories.  Only	a 5MB partition	is created by default, which
	 may not be sufficient for your	purposes.  To override this, you can
	 create	the file /conf/base/etc/md_size	containing the size, in	512
	 byte sectors, of the memory disk to create for	that directory.

	 You then typically provide file-by-file overrides in the
	 /conf/default/etc directory.  At a minimum, you must provide over-
	 rides for /etc/fstab, /etc/rc.conf, and /etc/rc.local via
	 /conf/default/etc/fstab, /conf/default/etc/rc.conf, and

	 Overrides are hierarchical.  You can supply network-specific defaults
	 in the	/conf/<BROADCASTIP>/etc	directory, where <BROADCASTIP> repre-
	 sents the broadcast IP	address	of the diskless	system as given	to it
	 via BOOTP.  The diskless_remount and md_size features work in any of
	 these directories.  The configuration feature works on	directories
	 other then /etc, you simply create the	directory you wish to replace
	 or override in	/conf/{base,default,_broadcast_,_ip_}/*	and work it in
	 the same way that you work /etc.

	 Since you normally clone the server's /etc using the
	 /conf/base/etc/diskless_remount, you might wish to remove unneeded
	 files from the	memory file system.  For example, if the server	has a
	 firewall but you do not, you might wish to remove /etc/ipfw.conf.
	 You can do this by creating a /conf/base/<DIRECTORY>.remove file.
	 For example, /conf/base/etc.remove, which contains a list of relative
	 paths that the	boot scripts should remove from	the memory file	sys-

	 As a minimum, you normally need to have the following in

	       <SERVER>:<ROOT> /     nfs    ro 0 0
	       <SERVER>:/usr   /usr  nfs    ro 0 0

	 You also need to create a customized version of
	 /conf/default/etc/rc.conf which should	contain	the startup options
	 for the diskless client, and /conf/default/etc/rc.local which could
	 be empty but prevents the server's own	/etc/rc.local from leaking
	 onto the diskless system.

	 In rc.conf, most likely you will not need to set hostname and
	 ifconfig_* because these will be already set by the startup code.
	 Finally, it might be convenient to use	a case statement using
	 `hostname` as the switch variable to do machine-specific configura-
	 tion in case a	number of diskless clients share the same configura-
	 tion files.

     o	 The kernel for	the diskless clients, which will be loaded using NFS
	 or TFTP, must include support for the NFS client:

	       options NFSCL
	       options NFS_ROOT

	 If you	are using a boot mechanism that	does not pass network configu-
	 ration	to the kernel using the	kernel environment, you	will also need
	 to include the	following options:

	       options BOOTP
	       options BOOTP_NFSROOT
	       options BOOTP_COMPAT

	 Note: the PXE environment does	not require these options.

	 The diskless booting environment relies on memory-backed file systems
	 to support temporary local storage in the event that the root file
	 system	is mounted read-only; as such, it is necessary to add the fol-
	 lowing	to the device section of the kernel configuration:

	       device md

	 If you	use the	firewall, remember to default to "open", or your ker-
	 nel will not be able to send/receive the BOOTP	packets.

     Be	warned that using unencrypted NFS to mount root	and user partitions
     may expose	information such as encryption keys.

     ethers(5),	exports(5), make.conf(5), bootpd(8), mountd(8),	nfsd(8),
     pxeboot(8), reboot(8), tftpd(8)


     The diskless environment first appeared in	FreeBSD	2.2.5.

     This manpage is probably incomplete.

     FreeBSD sometimes requires	to write onto the root partition, so the
     startup scripts mount MFS file systems on some locations (e.g. /etc and
     /var), while trying to preserve the original content.  The	process	might
     not handle	all cases.

FreeBSD	13.0			  May 3, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help