GettingStarted: Update Bare-metal Provisioning chapter

- Add information about server notifications
- Restructure into subsections

Change-Id: I6fa6b41eb118acd68746cf2038c348f723c1f407
Signed-off-by: Martin Borg <martin.borg@enea.com>

1 files changed, 134 insertions, 71 deletions

diff --git a/doc/book-enea-nfv-access-getting-started/doc/bare_metal_provisioning.xml b/doc/book-enea-nfv-access-getting-started/doc/bare_metal_provisioning.xml
index 3e6869f..8ff70ee 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/bare_metal_provisioning.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/bare_metal_provisioning.xml
@@ -12,20 +12,21 @@
   <section id="bare_meta_prov_intro">
     <title>Introduction</title>
 
-    <para>Bare Metal Provisioning can be used for automated deployment of the Enea
-    NFV Access Run Time Platform on a large number of uCPE devices. The uCPE
-    devices may have no previous operating system installed, or are reinstalled 
-      without preserving any existing data. Enea NFV Access Bare
-    Metal Provisioning is based on standardized Pre-Boot Execution environment (PXE) booting.</para>
+    <para>Bare Metal Provisioning can be used for automated deployment of the
+    Enea NFV Access Run Time Platform on a large number of uCPE devices. The
+    uCPE devices may have no previous operating system installed, or are
+    reinstalled without preserving any existing data. Enea NFV Access Bare
+    Metal Provisioning is based on standardized Pre-Boot Execution environment
+    (PXE) booting.</para>
 
     <para>The Bare Metal Provisioning process begins by PXE booting an Enea
-      NFV Access installer <literal>initramfs</literal> image. The installer downloads a
-    configuration file, as well as the Enea NFV Access Run Time Platform image and
-    then proceeds to install the system by dividing the disk into 2 partitions. A GPT
-    partition containing the GRUB boot loader and a second partition
-    containing the Enea NFV Access Run Time Platform root filesystem. When the
-    installation is complete, the uCPE device is automatically rebooted into
-    Enea NFV Access Run Time Platform.</para>
+    NFV Access installer <literal>initramfs</literal> image. The installer
+    downloads a configuration file, as well as the Enea NFV Access Run Time
+    Platform image and then proceeds to install the system by dividing the
+    disk into 2 partitions. A GPT partition containing the GRUB boot loader
+    and a second partition containing the Enea NFV Access Run Time Platform
+    root filesystem. When the installation is complete, the uCPE device is
+    automatically rebooted into Enea NFV Access Run Time Platform.</para>
   </section>
 
   <section id="bare_meta_prov_prereq">
@@ -40,13 +41,15 @@
       </listitem>
 
       <listitem>
-        <para>An HTTP server must be available in the provisioning
-        network.</para>
+        <para>An HTTP server must be available and accessible from the uCPE
+        devices in the provisioning network. Note that the installer will use
+        the same interface that the uCPE device is PXE-booted from, to obtain
+        an IP address using DHCP and access the HTTP server.</para>
       </listitem>
 
       <listitem>
-        <para>The uCPE devices are preconfigured in BIOS to boot from the
-        hard drive where the Enea NFV Access Run Time Platform will be
+        <para>The uCPE devices are preconfigured in BIOS to boot from the hard
+        drive where the Enea NFV Access Run Time Platform will be
         installed.</para>
       </listitem>
 
@@ -58,71 +61,114 @@
     </itemizedlist>
   </section>
 
-  <section id="bare_meta_prov_conf">
-    <title>Installation Configuration File</title>
+  <section id="bare_meta_prov_server">
+    <title>Server Configuration</title>
 
-    <para>An installation configuration file needs to be available on an HTTP
-    server in the provisioning network.</para>
-    
-    <note><para>The installer will use the same interface that the uCPE device 
-      was PXE-booted from, to obtain an IP address (using DHCP) and access the HTTP server.</para></note>
-
-    <para>The configuration parameters are described below. The configuration
-    file format is a list of <literal>"name = value"</literal> pairs.</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><literal>image_url</literal>. The HTTP URL used for downloading
-        the Enea NFV Access Run Time Platform image (in gzip compressed hddimg
-        format) to be installed on the uCPE device(s). This image is provided
-        with your Enea NFV Access release. This parameter is mandatory.</para>
-      </listitem>
+    <para>The following images provided with your Enea NFV Access release
+    needs to be made available on the PXE and HTTP servers:</para>
 
+    <orderedlist>
       <listitem>
-        <para><literal>install_drive</literal>. The name of the drive where
-        the Enea NFV Access Run Time Platform will be installed (e.g /dev/sda).
-        This parameter is optional. If no value is set, the installer will use
-        the largest detected (non-USB) drive on the uCPE device.</para>
+        <para>Copy the Enea NFV Access installer <literal>initramfs</literal>
+        image and kernel <literal>bzImage</literal> for the uCPE device
+        architecture to the TFTP directory on the PXE server (e.g
+        <literal>/var/lib/tftpboot</literal>).</para>
       </listitem>
 
       <listitem>
-        <para><literal>prompt_user</literal>. If the parameter is set to
-        "yes", the installer will prompt the user before formatting and
-        partitioning the drive. This parameter is optional. The default
-        behaviour is to not prompt the user (unattended installation).</para>
+        <para>Compress the Enea NFV Access Run Time Platform
+        <literal>hddimg</literal> image for the uCPE device architecture using
+        <literal>gzip</literal> and copy the resulting
+        <literal>hddimg.gz</literal> file to the HTTP server.</para>
       </listitem>
-    </itemizedlist>
-
-    <para>Installation Configuration File Example:</para>
-
-    <programlisting>
-        image_url = http://192.168.1.100/enea-nfv-access-xeon-d.hddimg.gz
-        install_drive = /dev/sda
-    </programlisting>
-  </section>
-
-  <section id="bare_meta_prov_pxe">
-    <title>PXE Configuration</title>
-
-    <para>Copy the Enea NFV Access installer <literal>initramfs</literal> image and kernel 
-      to the <literal>tftpboot</literal> directory on the PXE server (e.g
-    <literal>/var/lib/tftpboot</literal>). These files are provided with your
-    Enea NFV Access release.</para>
-
-    <para>A PXE entry for the Enea NFV Access installation needs to be added as
-    the default boot selection in the pxelinux configuration file (e.g
-    <literal>/var/lib/tftpboot/pxelinux.cfg/default</literal>). The PXE entry
-    should have the following settings:</para>
-
-    <programlisting>
+    </orderedlist>
+
+    <section id="bare_meta_prov_install_config">
+      <title>Installation Configuration File</title>
+
+      <para>An installation configuration file needs to be prepared on the
+      HTTP server. The format of the configuration file is a list of
+      "<literal>name = value</literal>" pairs and the available parameters are
+      described below.</para>
+
+      <para>Mandatory parameters:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><literal>image_url</literal>. The HTTP server URL used for
+          downloading the Enea NFV Access Run Time Platform image to be
+          installed on the uCPE devices in <literal>hddimg.gz</literal>
+          format.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Optional parameters:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><literal>install_drive</literal>. The name of the drive where
+          the Enea NFV Access Run Time Platform will be installed (e.g
+          <literal>/dev/sda</literal>). If not set, the installer will use the
+          largest detected (non-USB) drive on the uCPE device.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>prompt_user</literal>. If the parameter is set to
+          "yes", the installer will ask for confirmation before formatting and
+          partitioning the drive. The default behaviour is to proceed
+          automatically without any user interaction.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Optional parameters for sending status notifications to a server.
+      All three must be provided if used:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><literal>notify_user</literal>. Server SSH username</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>notify_pass</literal>. Server SSH password</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>notify_path</literal>. Location where notification
+          files will be placed, specified in "Server IP:directory"
+          format.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Installation Configuration File Example:</para>
+
+      <programlisting>
+ image_url = http://192.168.1.100/enea-nfv-access-xeon-d.hddimg.gz
+ install_drive = /dev/sda
+ notify_user = username
+ notify_pass = password
+ notify_path = 192.168.1.100:/home/user/status_notifications
+
+</programlisting>
+    </section>
+
+    <section id="bare_meta_prov_pxe">
+      <title>PXE Configuration</title>
+
+      <para>A PXE entry for the Enea NFV Access installation needs to be added
+      as the default boot selection in the pxelinux configuration file (e.g
+      <literal>/var/lib/tftpboot/pxelinux.cfg/default</literal>). The PXE
+      entry should have the following settings:</para>
+
+      <programlisting>
         default nfv_access
         label nfv_access
         menu label ^NFV_ACCESS_INSTALLER
         kernel &lt;Path to kernel&gt;
         append root=/dev/ram0 initrd=&lt;Path to initramfs&gt; LABEL=pxe-installer \
-        INSTALL_CFG=http://&lt;Server IP&gt;/&lt;Path to configuration file&gt;
+           INSTALL_CFG=http://&lt;Server IP&gt;/&lt;Path to install config file&gt;
         ipappend 2
     </programlisting>
+    </section>
   </section>
 
   <section id="bare_meta_prov_inst">
@@ -130,8 +176,8 @@
 
     <para>To initiate the installation, set the boot device (for next boot
     only) to PXE and reboot the uCPE devices. How to do this depends on the
-    remote management capabilities of the uCPE devices and may be
-    vendor-specific.</para>
+    remote management capabilities of the uCPE devices and may require
+    vendor-specific tools.</para>
 
     <para>Example initiation using <literal>ipmitool</literal>:</para>
 
@@ -141,7 +187,24 @@
     </programlisting>
 
     <para>The uCPE devices should be configured in BIOS to boot from the
-    installation drive first in order to automatically start the Enea NFV Access
-    Run Time Platform when the installation is finished.</para>
+    installation drive first in order to automatically start the Enea NFV
+    Access Run Time Platform when the installation is finished.</para>
+
+    <section>
+      <title>Server Notifications</title>
+
+      <para>Optionally, the uCPE devices can send a notification file to a
+      server once the installation is complete and Enea NFV Access Runtime
+      Platform has successfully booted. Notifications are enabled by providing
+      the <literal>notify_*</literal> parameters in the installation
+      configuration file.</para>
+
+      <para>Each uCPE device will push a file to the server location specified
+      in the installation configuration file. The file name will be the MAC
+      address of the PXE boot network interface in order to uniquely identify
+      the device. Note that the status notification will only be sent on the
+      first boot after installation is done, subsequent reboots of the uCPE
+      device will not cause any new notifications to be sent.</para>
+    </section>
   </section>
 </chapter>
\ No newline at end of file