Extensive documentation changes to the script, but only

comments and empty lines have been touched.

All of this should go in the diskless(8) manpage, now if we had
some kind of 'literate programming' tool to extract the comments
from the script and put them in a reasonable nroff format, it
would be a lot easier to keep code and docs in sync

1 files changed, 87 insertions, 49 deletions

diff --git a/etc/rc.initdiskless b/etc/rc.initdiskless
index 56a19c1..b84dab9 100644
--- a/etc/rc.initdiskless
+++ b/etc/rc.initdiskless
@@ -31,58 +31,96 @@
 
 
 # On entry to this script the entire system consists of a read-only root
-# mounted via NFS.  We use the contents of /conf to create and populate
-# memory filesystems.  The kernel has run BOOTP and configured an interface
+# mounted via NFS. The kernel has run BOOTP and configured an interface
 # (otherwise it would not have been able to mount the NFS root!)
 #
-# The following directories are scanned.  Each sucessive directory overrides
-# (is merged into) the previous one.
-#
-#	/conf/base		universal base
-#	/conf/default		modified by a secondary universal base
-#	/conf/${ipba}		modified based on the assigned broadcast IP
-#	/conf/${ip}		modified based on the machine's assigned IP
-#
-# Each of these directories may contain any number of subdirectories which
-# represent directories in / on the diskless machine.  The existance of
-# these subdirectories causes this script to create a MEMORY FILESYSTEM for
-# /<sub_directory_name>.  For example, if /conf/base/etc exists then a
-# memory filesystem will be created for /etc.
-#
-# If a subdirectory contains the file 'remount' the contents of the file
-# is a mount command used to remount the subdirectory prior to it being
-# copied.  An example contents could be: "mount -o ro /dev/ad0s3".  Note
-# that the directory to be mounted on is supplied by this script.
-#
-# If a subdirectory contains the file 'diskless_remount' the contents of
-# the file is used to remount the subdirectory prior to it being copied to
-# the memory filesystem.  For example, if /conf/base/etc/diskless_remount
-# contains the string 'my.server.com:/etc' then my.server.com:/etc will be
-# mounted in place of the subdirectory.  This allows you to avoid making
-# duplicates of system directories in /conf.  Special processing is done
-# to allow specifications relative to the root filesystem.
-#
-# If a subdirectory contains the file 'md_size', the contents of the
-# file is used to determine the size of the memory filesystem, in 512
-# byte sectors.  The default is 10240 (5MB).  You only have to specify an
-# md_size if the default doesn't work for you (i.e. if it is too big or
-# too small).  For example, /conf/base/etc/md_size might contain '16384'.
-#
-# If /conf/<special_dir>/SUBDIR.cpio.gz exists, the file is cpio'd into
-# the specified /SUBDIR (and a memory filesystem is created for /SUBDIR
-# if necessary).
-#
-# If /conf/<special_dir>/SUBDIR.remove exists, the file contains a list
-# of paths which are rm -rf'd relative to /SUBDIR.
-#
-# You will almost universally want to create a /conf/base/etc containing
-# a diskless_remount and possibly an md_size file.  You will then almost
-# universally want to override rc.conf, rc.local, and fstab by creating
-# /conf/default/etc/{rc.conf,rc.local,fstab}.  Your fstab should be sure
-# to mount a /usr... typically an NFS readonly /usr.
-#
-# NOTE!  /var, /tmp, and /dev will be created elsewhere.
+# We use the contents of /conf to create and populate memory filesystems
+# that are mounted on top of this root to implement the writable
+# (and host-specific) parts of the root filesystem, and other volatile
+# filesystems.
+#
+# The hierarchy in /conf has the form /conf/T/M/ where M are directories
+# for which memory filesystems will be created and filled,
+# and T is one of the "template" directories below:
+#
+#  base		universal base, typically a replica of the original root;
+#  default	secondary universal base, typically overriding some
+#		of the files in the original root;
+#  ${ipba}	where ${ipba} is the assigned broadcast IP address
+#  ${class}	where ${class} is a list of directories supplied by
+#		bootp/dhcp through the T134 option.
+#		${ipba} and ${class} are typicall used to configure features
+#		for group of diskless clients, or even individual features;
+#  ${ip}	where ${ip} is the machine's assigned IP address, typically
+#		used to set host-specific features;
+#		
+# Template directories are scanned in the order they are listed above,
+# with each sucessive directory overriding (merged into) the previous one;
+# non-existing directories are ignored.
+#
+# The existence of a directory /conf/T/M causes this script to create a
+# memory filesystem mounted as /M on the client.
+#
+# Some files in /conf have special meaning, namely:
+#
+# Filename	Action
+# ----------------------------------------------------------------
+# /conf/T/M/remount
+#		The contents of the file is a mount command. E.g. if
+# 		/conf/1.2.3.4/foo/remount contains "mount -o ro /dev/ad0s3",
+#		then /dev/ad0s3 will be be mounted on /conf/1.2.3.4/foo/
+#
+# /conf/T/M/diskless_remount
+#		The contents of the file points to an NFS filesystem. E.g. if
+#		/conf/base/etc/diskless_remount contains "foo.com:/etc",
+#		then foo.com:/etc will be be mounted on /conf/base/etc/
+#		If the file contains a pathname starting with "/", then
+#		the root path is prepended to it; this allows relocation of
+#		the root filesystem withouth changing configuration files.
+#
+# /conf/T/M/md_size
+#		The contents of the file specifies the size of the memory
+#		filesystem to be created, in 512 byte blocks.
+#		The default size is 10240 blocks (5MB). E.g. if
+#		/conf/base/etc/md_size contains "30000" then a 15MB MFS
+#		will be created. In case of multiple entries for the same
+#		directory M, the last one in the scanning order is used.
+#		NOTE: If you only need to create a memory filesystem but not
+#		initialize it from a template, it is preferrable to specify
+#		it in fstab e.g. as  "md /tmp mfs -s=30m,rw 0 0"
+#
+# /conf/T/SUBDIR.cpio.gz
+#		The file is cpio'd into /SUBDIR (and a memory filesystem is
+#		created for /SUBDIR if necessary). The presence of this file
+#		prevents the copy from /conf/T/SUBDIR/
+#
+# /conf/T/SUBDIR.remove
+#		The list of paths contained in the file are rm -rf'd
+#		relative to /SUBDIR.
+#
+# You will almost universally want to create the following files under /conf
+#
+# File				Content
+# ----------------------------	------------------------------------------
+# /conf/base/etc/md_size	size of /etc filesystem
+# /conf/base/diskless_remount	"/etc"
+# /conf/default/etc/rc.conf	generic diskless config parameters
+# /conf/default/etc/fstab	generic diskless fstab e.g. like this
+#
+#	foo:/root_part		/	nfs	ro		0 0
+#	foo:/usr_part		/usr	nfs     ro		0 0
+#	foo:/home_part		/home   nfs     rw      	0 0
+#	md			/tmp	mfs     -s=30m,rw	0 0
+#	md			/var	mfs	-s=30m,rw	0 0
+#	proc			/proc	procfs	rw		0 0
+#
+# plus, possibly, overrides for password files etc.
+#
+# NOTE!  /var, /tmp, and /dev will be typically created elsewhere, e.g.
+# as entries in the fstab as above.
 # Those filesystems should not be specified in /conf.
+#
+# (end of documentation, now get to the real code)
 
 dlv=`/sbin/sysctl -n vfs.nfs.diskless_valid 2> /dev/null`
 [ ${dlv:=0} -eq 0 ] && [ ! -f /etc/diskless ] && exit 0