Add support for "first boot" rc.d scripts. [1]

These scripts, containing
# KEYWORD: firstboot
will only be run if a sentinel file (default: /firstboot, configurable
via the rc.conf ${firstboot_sentinel} variable) exists; this sentinel
file will be deleted at the end of the boot process.

Scripts can request that the system reboot after the first boot by
creating the file ${firstboot_sentinel}-reboot.

This functionality is expected to be useful for embedded systems and
virtual machine images, where it may be desirable to
(a) download and install updates which became available between when
the image was created and when it was "turned on";
(b) download and install packages which may be newer than those
which were available when the image was created;
(c) install packages which run binaries during their install process,
bypassing the problem of cross-architecture installs;
(d) resize filesystems to match the disk onto which a VM image was
installed;
(e) perform initialization tasks relevant to cloud systems (e.g.,
Amazon's Elastic Compute Cloud);
and likely to perform many other one-time initialization functions.

Document this new functionality in rc.conf(5) and rc(8). [2]

Reviewed by:	freebsd-current, freebsd-rc [1]
Reviewed by:	Warren Block [2]
MFC after:	3 days

4 files changed, 63 insertions, 4 deletions

diff --git a/etc/defaults/rc.conf b/etc/defaults/rc.conf
index b04d7cf..471fb3c 100644
--- a/etc/defaults/rc.conf
+++ b/etc/defaults/rc.conf
@@ -621,6 +621,9 @@ quotacheck_flags="-a"	# Check all file system quotas (if enabled)
 accounting_enable="NO"	# Turn on process accounting (or NO).
 ibcs2_enable="NO"	# Ibcs2 (SCO) emulation loaded at startup (or NO).
 ibcs2_loaders="coff"	# List of additional Ibcs2 loaders (or NO).
+firstboot_sentinel="/firstboot"	# Scripts with "firstboot" keyword are run if
+			# this file exists.  Should be on a R/W filesystem so
+			# the file can be deleted after the boot completes.
 
 # Emulation/compatibility services provided by /etc/rc.d/abi
 sysvipc_enable="NO"	# Load System V IPC primitives at startup (or NO).
diff --git a/etc/rc b/etc/rc
index 59dece8..fd5ff85 100644
--- a/etc/rc
+++ b/etc/rc
@@ -82,10 +82,15 @@ if [ `/sbin/sysctl -n security.jail.jailed` -eq 1 ]; then
 	fi
 fi
 
+# If the firstboot sentinel doesn't exist, we want to skip firstboot scripts.
+if ! [ -e ${firstboot_sentinel} ]; then
+	skip_firstboot="-s firstboot"
+fi
+
 # Do a first pass to get everything up to $early_late_divider so that
 # we can do a second pass that includes $local_startup directories
 #
-files=`rcorder ${skip} /etc/rc.d/* 2>/dev/null`
+files=`rcorder ${skip} ${skip_firstboot} /etc/rc.d/* 2>/dev/null`
 
 _rc_elem_done=' '
 for _rc_elem in ${files}; do
@@ -107,7 +112,13 @@ case ${local_startup} in
 *)	find_local_scripts_new ;;
 esac
 
-files=`rcorder ${skip} /etc/rc.d/* ${local_rc} 2>/dev/null`
+# The firstboot sentinel might be on a newly mounted filesystem; look for it
+# again and unset skip_firstboot if we find it.
+if [ -e ${firstboot_sentinel} ]; then
+	skip_firstboot=""
+fi
+
+files=`rcorder ${skip} ${skip_firstboot} /etc/rc.d/* ${local_rc} 2>/dev/null`
 for _rc_elem in ${files}; do
 	case "$_rc_elem_done" in
 	*" $_rc_elem "*)	continue ;;
@@ -116,6 +127,15 @@ for _rc_elem in ${files}; do
 	run_rc_script ${_rc_elem} ${_boot}
 done
 
+# Remove the firstboot sentinel, and reboot if it was requested.
+if [ -e ${firstboot_sentinel} ]; then
+	rm ${firstboot_sentinel}
+	if [ -e ${firstboot_sentinel}-reboot ]; then
+		rm ${firstboot_sentinel}-reboot
+		kill -INT 1
+	fi
+fi
+
 echo ''
 date
 exit 0
diff --git a/share/man/man5/rc.conf.5 b/share/man/man5/rc.conf.5
index 799f535..2a0f3ba 100644
--- a/share/man/man5/rc.conf.5
+++ b/share/man/man5/rc.conf.5
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 12, 2013
+.Dd October 19, 2013
 .Dt RC.CONF 5
 .Os
 .Sh NAME
@@ -3675,6 +3675,23 @@ and if
 is set to
 .Dq Li YES ,
 this specifies a list of additional iBCS2 loaders to enable.
+.It Va firstboot_sentinel
+.Pq Vt str
+This variable specifies the full path to a
+.Dq first boot
+sentinel file.
+If a file exists with this path,
+.Pa rc.d
+scripts with the
+.Dq firstboot
+keyword will be run on startup and the sentinel file will be deleted
+after the boot process completes.
+The sentinel file must be located on a writable file system which is
+mounted no later than
+.Va early_late_divider
+to function properly.
+The default is
+.Pa /firstboot .
 .It Va linux_enable
 .Pq Vt bool
 Set to
diff --git a/share/man/man8/rc.8 b/share/man/man8/rc.8
index 32d0ade..cfeb0e6 100644
--- a/share/man/man8/rc.8
+++ b/share/man/man8/rc.8
@@ -35,7 +35,7 @@
 .\"     @(#)rc.8	8.2 (Berkeley) 12/11/93
 .\" $FreeBSD$
 .\"
-.Dd September 23, 2013
+.Dd October 19, 2013
 .Dt RC 8
 .Os
 .Sh NAME
@@ -129,6 +129,13 @@ and add
 (only allow vnet-enabled jails) to the list of KEYWORDS to skip in
 .Xr rcorder 8 .
 .It
+If the file
+.Va ${firstboot_sentinel}
+does not exist, add
+.Dq Li firstboot
+to the list of KEYWORDS to skip in
+.Xr rcorder 8 .
+.It
 Invoke
 .Xr rcorder 8
 to order the files in
@@ -156,6 +163,11 @@ Stop processing when the script that is the value of the
 .Va $early_late_divider
 has been run.
 .It
+Check again to see if the file
+.Va ${firstboot_sentinel}
+exists (in case it is located on a newly mounted file system)
+and adjust the list of KEYWORDs to skip appropriately.
+.It
 Re-run
 .Xr rcorder 8 ,
 this time including the scripts in the
@@ -164,6 +176,13 @@ directories.
 Ignore everything up to the
 .Va $early_late_divider ,
 then start executing the scripts as described above.
+.It
+If the file
+.Va ${firstboot_sentinel}
+exists, delete it.
+If the file
+.Va ${firstboot_sentinel}-reboot
+also exists (because it was created by a script), then delete it and reboot.
 .El
 .Ss Operation of Nm rc.shutdown
 .Bl -enum