GettingStarted: Add Bare Metal Provisioning chapter

Change-Id: I86b67a965cf86bad653947766a3698cbe62da091
Signed-off-by: Sona Sarmadi <sona.sarmadi@enea.com>
Signed-off-by: Martin Borg <martin.borg@enea.com>

2 files changed, 150 insertions, 0 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
new file mode 100644
index 0000000..3e6869f
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/bare_metal_provisioning.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<chapter id="bare_meta_prov">
+  <title>Bare Metal Provisioning</title>
+
+  <para>This chapter contains information needed in order to use Bare Metal
+  Provisioning. Bare Metal Provisioning is an optional feature in the Enea NFV
+  Access Run Time Platform. If you do not intend to use this feature, skip to
+  the next chapter.</para>
+
+  <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>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>
+  </section>
+
+  <section id="bare_meta_prov_prereq">
+    <title>Prerequisites</title>
+
+    <itemizedlist>
+      <listitem>
+        <para>The uCPE devices to be installed are connected in a working PXE
+        network boot environment. The PXE server can be set up using any Linux
+        distribution that includes TFTP and DHCP software packages. Refer to
+        the documentation for your distribution for setup instructions.</para>
+      </listitem>
+
+      <listitem>
+        <para>An HTTP server must be available in the provisioning
+        network.</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
+        installed.</para>
+      </listitem>
+
+      <listitem>
+        <para>A remote management tool is available that can be used to set
+        the next boot option to PXE and reboot the uCPE devices in order to
+        begin the installation.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="bare_meta_prov_conf">
+    <title>Installation Configuration File</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>
+
+      <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>
+      </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>
+      </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>
+        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;
+        ipappend 2
+    </programlisting>
+  </section>
+
+  <section id="bare_meta_prov_inst">
+    <title>Starting the Installation</title>
+
+    <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>
+
+    <para>Example initiation using <literal>ipmitool</literal>:</para>
+
+    <programlisting>
+        ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; chassis bootdev pxe
+        ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; power reset
+    </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>
+  </section>
+</chapter>
\ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/book.xml b/doc/book-enea-nfv-access-getting-started/doc/book.xml
index 534b7f9..abce2c2 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/book.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/book.xml
@@ -27,6 +27,9 @@
   <xi:include href="secure_boot.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
 
+<xi:include href="bare_metal_provisioning.xml"
+              xmlns:xi="http://www.w3.org/2001/XInclude" />
+
   <xi:include href="getting_started_ucpe_manager.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />