From 6aead8d49c6aa020ef6630d25f30df9df1ace5d2 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Sat, 25 Mar 2017 17:16:13 +0200
Subject: Implement buildid monitoring and automatic reboot

---
 doc/manual.cli | 30 +++++++++++++++++++++---------
 1 file changed, 21 insertions(+), 9 deletions(-)

(limited to 'doc/manual.cli')

diff --git a/doc/manual.cli b/doc/manual.cli
index 961627e..863841c 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -34,9 +34,17 @@ mode} and receive \i{build tasks} from their respective agents.
 \h1#boot|Booting|
 
 \c{buildos} is normally booted from the network using PXE but can also be
-booted locally from initrd directly.
+booted locally from the kernel image and initrd directly.
 
-\h2#boot-net|Network|
+\h2#boot-reboot|Reboot|
+
+Build OS can detect when the OS build has been updated and automatically
+reboot the build host. This is achieved by polling the URL specified
+with the \c{buildos.buildid_url} kernel command line parameter. It should
+point to the \c{buildos-buildid} file that comes along the kernel image
+and initrd. See \l{#boot-net Network Boot} for the usage example.
+
+\h2#boot-net|Network Boot|
 
 Here we assume that you have already established your PXE setup using
 PXELINUX. That is, you have configured a TFTP server that hosts the
@@ -47,18 +55,20 @@ To setup PXE boot of \c{buildos}, perform the following steps:
 
 \ol|
 
-\li|Copy the kernel image and initrd to the TFTP server. For example:
+\li|Copy the Build OS \c{-image}, \c{-initrd}, and \c{-buildid} files to the
+TFTP server. For example:
 
 \
 # mkdir -p /var/lib/tftpboot/buildos
-# cp buildos-image buildos-initrd /var/lib/tftpboot/buildos/
+# cp buildos-image buildos-initrd buildos-buildid \
+  /var/lib/tftpboot/buildos/
 \
 
 |
 
-\li|Assuming the host has MAC address \c{de:ad:be:ef:b8:da}, create a
+\li|Assuming the host MAC address is \c{de:ad:be:ef:b8:da}, create a
     host-specific configuration file (or use \c{default} as the last path
-    component for a configuration that applies to all the hosts):
+    component for a configuration that applies to all hosts):
 
 \
 # cat <<EOF >/var/lib/tftpboot/pxelinux.cfg/01-de-ad-be-ef-b8-da
@@ -70,11 +80,13 @@ label buildos
   menu label buildos
   kernel /buildos/buildos-image
   initrd /buildos/buildos-initrd
-  append buildos.smtp_relay=example.org buildos.admin_email=admin@example.org
+  append buildos.smtp_relay=example.org buildos.admin_email=admin@example.org buildos.buildid_url=tftp://<tftp-host>/buildos/buildos-buildid
 EOF
 \
 
-|
+Where \c{<tftp-host>} in \c{buildid_url} is the address of the TFTP server
+(the same address as returned by the DHCP server to PXE clients). Note that
+all the parameters in \c{append} must be specified on a single line.|
 
 \li|You can test the setup using QEMU/KVM, for example:
 
@@ -88,7 +100,7 @@ $ sudo kvm \
 
 ||
 
-\h2#boot-local|Local|
+\h2#boot-local|Local Boot|
 
 During testing it is often useful to boot \c{buildos} directly from the
 kernel image and initrd files. As an example, here is how this can be done
-- 
cgit v1.1