Bring the diskless manual page more up-to-date. It still needs a lot of work.

1 files changed, 157 insertions, 88 deletions

diff --git a/share/man/man8/diskless.8 b/share/man/man8/diskless.8
index e6a49f1..f368a5e 100644
--- a/share/man/man8/diskless.8
+++ b/share/man/man8/diskless.8
@@ -38,7 +38,7 @@ The ability to boot a machine over the network is useful for
 or
 .Em dataless
 machines, or as a temporary measure while repairing or
-re-installing file systems on a local disk.
+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
@@ -47,53 +47,66 @@ phases of interaction between client and server:
 .Pp
 .Bl -enum -compact
 .It
-The stage-1 bootstrap loads a boot program, from
+The stage-1 bootstrap, typically PXE built into your ethernet
+card, loads a second-stage boot program.
 .It
-The boot program loads a kernel.
+The second-stage boot program, typically 'pxeboot', loads modules and
+the kernel and boots the kernel.
 .It
-The kernel does NFS mounts for root.
+The kernel NFS mounts the root directory and continues from there.
 .El
 .Pp
 Each of these phases are described in further detail below.
 .Pp
-In phase 1, the stage-1 bootstrap code loads a boot program,
-which is typically able to control the network card.
-The boot program can be stored in the BIOS, in a BOOT ROM
-located on the network card (PXE, etherboot, netboot),
-or come from a disk unit (e.g. etherboot or netboot).
+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
+.Pa /boot/pxeboot
+into the tftp directory on the server, which is typically
+.Pa /tftpdir .
 .Pp
-In phase 2, the boot program loads a kernel.
-Operation in
-this phase depends on the design of the boot program.
-Typically, the boot program uses the
-.Tn BOOTP
-or
-.Tn DHCP
-protocol to get the client's IP address and other boot
-information, including but not limited to
-the IP addresses of the NFS server, router and nameserver,
-and the name of the kernel to load.
-Then the kernel is loaded, either directly using NFS
-(as it is the case for etherboot and netboot),
-or through an intermediate loader called pxeboot and
-loaded using TFTP or NFS.
+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
+.Pa /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.
+.Bd -literal -offset indent
+cd /usr/src/sys/i386/boot
+make clean; make; make install
+cp /boot/pxeboot /tftpdir/
+.Ed
 .Pp
-In phase 3, the kernel uses again DHCP or BOOTP to acquire
+In phase 3, the kernel again uses DHCP or BOOTP to acquire
 configuration information, and proceeds to mount the
-root file system and start operation.
-Some specific actions performed during the startup
-of a diskless system are listed in
+root filesystem and start operation.  The boot
+scripts recognize a diskless startup and peform 
+the actions found in
+.Pa /etc/rc.d/initdiskless
+and
+.Pa /etc/rc.d/diskless .
+In older systems the scripts are located in
 .Pa /etc/rc.diskless1
 and
-.Pa /etc/rc.diskless2
+.Pa /etc/rc.diskless2 .
 .Sh CONFIGURATION
 In order to run a diskless client, you need the following:
 .Bl -bullet
 .It
-an NFS server which exports a root and /usr partition with
+An NFS server which exports a root and /usr partition with
 appropriate permissions.
-The
-.Pa rc.diskless{1,2}
+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.
@@ -111,7 +124,7 @@ is the mountpoint on the server of the root partition.
 The script
 .Pa /usr/share/examples/diskless/clone_root
 can be used to create a shared readonly root partition,
-but in same cases you can also decide to export
+but in many cases you may decide to export
 (again as readonly) the root directory used by
 the server itself.
 .It
@@ -147,40 +160,104 @@ and
 .Aq ROOT
 have the obvious meanings.
 .It
-On the root partition, create the directory
-.Pa /conf/default/etc ,
-and populate it with a copy of the contents of
+A properly initialized root partition.
+The script
+.Pa /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,
+.Pa / ,
+and not try to clone it.
+.Pp
+You often do not want to use the same
+.Pa rc.conf
+or
+.Pa 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
+.Pa /etc
+(as well as other subdirectories of root).  The scripts provide four
+overriding directories situated in
+.Pa /conf/base ,
+.Pa /conf/default ,
+.Pa /conf/<broadcast-ip> ,
+and
+.Pa /conf/<machine-ip> .
+You should always create
+.Pa /conf/base/etc ,
+which will entirely replace the server's
+.Pa /etc
+on the diskless machine.
+You can clone the server's
+.Pa /etc
+here or you can create a special file which tells the diskless boot scripts
+to remount the server's
+.Pa /etc
+onto
+.Pa /conf/base/etc .
+You do this by creating the file
+.Pa /conf/base/etc/diskless_remount
+containing the mount point to use as a basis of the diskless machine's
 .Pa /etc .
-The files and subdirectories within
+For example, the file might contain:
+.Bd -literal -offset 4n
+10.0.0.1:/etc
+.Ed
+.Pp
+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
+.Pa /conf/base/etc/md_size
+containing the size, in 512 byte sectors, of the memory disk to create
+for that directory.
+.Pp
+You then typically provide file-by-file overrides in the
 .Pa /conf/default/etc
-are used to bootstrap the diskless environment's
-.Pa /etc
-memory file system.
-Be sure and copy the entirety of
+directory.  At a minimum you must provides overrides for
+.Pa /etc/fstab ,
+.Pa /etc/rc.conf ,
+and
+.Pa /etc/rc.local
+via
+.Pa /conf/default/etc/fstab ,
+.Pa /conf/default/etc/rc.conf ,
+and
+.Pa /conf/default/etc/rc.local .
+.Pp
+Overrides are hierarchical.  You can supply network-specific defaults
+in the
+.Pa /conf/<BROADCASTIP>/etc
+directory, where <BROADCASTIP> represents the broadcast IP address of
+the diskless system as given to it via
+.Tn BOOTP .
+The
+.Pa diskless_remount
+and
+.Pa md_size
+features work in any of these directories.
+The configuration feature works on directories other then
 .Pa /etc ,
-and not just overrides.
-.It
-Additionally, one may supply per-network or per-host overrides for
-files in
-.Pa /etc
-by creating and populating the directories
-.Pa /conf/${i}/etc ,
-where
-.Va i
-can be either the subnet broadcast address for the client, or the IP
-address of the client.
+you simply create the directory you wish to replace or override in
+.Pa /conf/{base,default,<broadcast>,<ip>}/*
+and work it in the same way that you work
+.Pa /etc .
 .Pp
-Files are copied from the above directories into
+Since you normally clone the server's
 .Pa /etc
-(overriding the previous content of
-.Pa /etc )
-starting from the most generic one by
-.Pa /etc/rc.diskless1 ,
-before the main part of
-.Pa /etc/rc
-(including reading
-.Pa rc.conf )
-is run.
+using the
+.Pa /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
+.Pa /etc/ipfw.conf .
+You can do this by creating a
+.Pa /conf/base/<DIRECTORY>.remove
+file.  For example,
+.Pa /conf/base/etc.remove ,
+which contains a list of relative paths that the boot scripts should remove
+from the memory file systems.
 .Pp
 As a minimum, you normally need to have the following in
 .Pa /conf/default/etc/fstab
@@ -190,32 +267,23 @@ As a minimum, you normally need to have the following in
 proc            /proc procfs rw 0 0
 .Ed
 .Pp
-and also a customized version of
+You also need to create a customized version of
 .Pa /conf/default/etc/rc.conf
 which should contain
-the startup options for the diskless client.
+the startup options for the diskless client, and
+.Pa /conf/default/etc/rc.local
+which could be empty but prevents the server's own
+.Pa /etc/rc.local
+from leaking onto the diskless system.
 .Pp
-Most likely
+In
+.Pa 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.
-You will also probably need to set
-.Va local_startup Ns = Ns Qq
-so that the server's
-local startup files will not be used.
-.Pp
-While an
-.Xr md 4 Ns -backed
-file system is mounted on
-.Pa /var
-by the startup scripts,
-some sites may want to disable the saving of entropy by setting
-.Va entropy_dir Ns = Ns Qq Li NO
-in
-.Pa /etc/defaults/rc.conf .
-.Pp
 Finally, it might be convenient to use a
 .Ic case
 statement using
@@ -224,16 +292,19 @@ as the switch variable to do machine-specific configuration
 in case a number of diskless clients share the same configuration
 files.
 .It
-build a kernel whose config file (e.g.\&
-.Pa /sys/i386/conf/DISKLESS )
-has at least the following options and devices:
+The kernel for the diskless clients, which will be loaded using
+NFS or TFTP, should be built with at least the following options:
 .Bd -literal -offset indent
-device md
 options BOOTP
 options BOOTP_NFSROOT
 options BOOTP_COMPAT
 .Ed
 .Pp
+In the devices section add:
+.Bd -literal -offset indent
+device md
+.Ed
+.Pp
 If you use the firewall, remember to default to open or your kernel
 will not be able to send/receive the bootp packets.
 .El
@@ -246,9 +317,8 @@ This manpage is probably incomplete.
 .Pp
 .Fx
 sometimes requires to write onto
-the root partition, so the startup scripts create and mount
-.Xr md 4 Ns -backed
-file systems on some locations (e.g.\&
+the root partition, so the startup scripts mount MFS
+filesystems on some locations (e.g.\&
 .Pa /etc
 and
 .Pa /var ) ,
@@ -256,7 +326,6 @@ while
 trying to preserve the original content.
 The process might not handle all cases.
 .Sh SEE ALSO
-.Xr md 4 ,
 .Xr ethers 5 ,
 .Xr exports 5 ,
 .Xr bootpd 8 ,