path: root/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml

<?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="plat-release-content">
  <title>Getting Started with Enea NFV Access</title>

  <section id="access_installer">
    <title>Enea NFV Access Run Time Platform Installer</title>

    <para>The current release supports two methods of installation:</para>
    
    <itemizedlist>
      <listitem><para>Manual installation from a USB stick using the Enea NFV Access Web-installer,
      which guarantees a clean installation of NFV Access on a uCPE device.</para></listitem>
      <listitem><para>Mass installation and automated deployment using
        Bare Metal Provisioning.</para></listitem>
    </itemizedlist>
      
      <para>For more information about Bare Metal Provisioning please refer 
        to <xref linkend="bare_meta_prov">5.3, Bare Metal Provisioning"</xref>.</para>

    <section id="prereq">
      <title>Prerequisites</title>

      <para>To install the Enea NFV Access Run Time Platform, 3 things are
      required: a USB stick (16GB or larger), a development machine with root
      permissions (Linux or Windows) and a uCPE device.</para>

      <para>Minimal requirements for the uCPE device:</para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>EFI and virtualization support.</para>
        </listitem>

        <listitem>
          <para>2 cores</para>
        </listitem>

        <listitem>
          <para>4GB RAM</para>
        </listitem>

        <listitem>
          <para>Storage Device (SSD recommended).</para>
        </listitem>
      </itemizedlist>

      <para>BIOS settings that need to be enabled:</para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>EFI</para>
        </listitem>

        <listitem>
          <para>Intel Virtualization Technology (VT-x)</para>
        </listitem>

        <listitem>
          <para>Intel Virtualization Technology for Directed I/O (VT-d)</para>
        </listitem>

        <listitem>
          <para>SR-IOV</para>
        </listitem>
      </itemizedlist>
    </section>

    <section condition="hidden" id="man_installer">
      <title>Installer Setup and Usage for a manual installation</title>

      <para><emphasis role="bold">To install Enea NFV Access Run Time Platform
      on a physical drive</emphasis></para>

      <orderedlist>
        <listitem>
          <para>Go to the installer location: <programlisting># cd &lt;path_to_EneaNFV_Access_folder&gt;/&lt;architecture&gt;/
install/nfv-installer/script-installer</programlisting></para>
        </listitem>

        <listitem>
          <para>Execute the installer script: <programlisting># sudo ./nfv_installer.sh</programlisting></para>
        </listitem>

        <listitem>
          <para>Optionally, press ENTER to see the list of available
          commands:<programlisting>help - displays a guide on how to use the installer
list-params - lists all available parameters
list-steps - lists the installer steps and the parameters that they depend on
set - sets a parameter (e.g. <literal>set drive=/dev/sda</literal>)
clear - clears a parameter (e.g. <literal>clear drive</literal>)
list-partitions - lists current drives and partitions
dry - performs a simulation test run
run - executes the installer, using the values you set for each parameter
q or quit - exits the script</programlisting></para>
        </listitem>

        <listitem>
          <para>Set the required parameters depending on what steps you want
          to run:</para>

          <note>
            <para>When using the installer for the first time, make sure to
            set ALL parameters in order to be able to run all steps. See <xref
                linkend="examples">
                 Example 2 
              </xref> for details.</para>
          </note>

          <para><programlisting># set &lt;parameter_name&gt;=&lt;parameter_value&gt;</programlisting></para>

          <itemizedlist spacing="compact">
            <listitem>
              <para><parameter>drive=&lt;/dev/sdaX&gt;</parameter> - sets the
              drive which will be partitioned.</para>
            </listitem>

            <listitem>
              <para><parameter>grub_binary=&lt;file&gt;</parameter> - points
              to the <filename>GRUB</filename> executable, which will be
              installed where <filename>grub_destination</filename> is
              set.</para>
            </listitem>

            <listitem>
              <para><parameter>grub_destination=&lt;drive&gt;</parameter> -
              specifies the partition where <filename>GRUB</filename> will be
              installed.</para>
            </listitem>

            <listitem>
              <para><parameter>rootfs_destination=&lt;drive&gt;</parameter> -
              specifies the partition where the <filename>rootfs</filename>
              will be deployed, used by <filename>GRUB</filename> to boot
              from.</para>
            </listitem>

            <listitem>
              <para><parameter>rootfs_targz=&lt;rootfs.tar.gz
              file&gt;</parameter> - sets the archive of the Enea NFV Access
              <filename>rootfs</filename> you wish to unpack. The archive will
              be unpacked where <filename>rootfs_destination</filename> is
              set. Which type of archive file you unpack depends on whether
              you are booting from an SSD/HDD or from a USB drive.</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Optionally, perform a test run before affecting the actual
          layout of the physical media, with the command: <programlisting>dry</programlisting></para>
        </listitem>

        <listitem>
          <para>Run the installer: <programlisting>run</programlisting></para>
        </listitem>

        <listitem>
          <para>Exit the script: <programlisting>quit</programlisting></para>
        </listitem>
      </orderedlist>

      <para>The Enea NFV Access installer creates a bootable media by
      performing three steps. Each of the following 3 steps is executed or not
      depending on whether certain parameters are set:</para>

      <itemizedlist>
        <listitem>
          <para>Format drive. Creates a 512MB partition to be used by
          <filename>GRUB</filename>, and another for use by the
          <filename>rootfs</filename>. The second partition should occupy the
          rest of the physical media, minus the first partition. This step
          depends on setting these parameter(s): <programlisting>drive=</programlisting></para>
        </listitem>

        <listitem>
          <para>GRUB install. Installs the <literal>grub_binary</literal> on
          the drive set for <literal>grub_destination</literal>. A
          <filename>grub.cfg</filename> file is created. This file is
          configured by the user, to boot from the
          <literal>rootfs_destination</literal>. This step depends on setting
          these parameter(s):<programlisting>grub_destination=
grub_binary=
rootfs_destination=</programlisting></para>
        </listitem>

        <listitem>
          <para>Root Filesystem install. Copies and unpacks the files found in
          <literal>rootfs_targz</literal> to the
          <literal>rootfs_destination</literal>. This step depends on setting
          these parameter(s):<programlisting>rootfs_targz=
rootfs_destination=</programlisting></para>
        </listitem>
      </itemizedlist>

      <para>After using the installer and setting up the bootable media,
      connect it to the uCPE device and configure the uCPE device to use it as
      a primary boot device.</para>
    </section>

    <section id="auto_installer">
      <title>Creating a bootable USB stick</title>

      <para>In order to install the Enea NFV Access Run Time Platform, you must
      first create a bootable USB stick with the image you intend to
      install. Follow the example below to proceed.</para>

      <para><emphasis role="bold">Create a bootable USB stick
      image</emphasis></para>

      <orderedlist>
        <listitem>
          <para>Copy the HDDIMG image file provided by Enea, onto a
          development machine.</para>
        </listitem>

        <listitem>
          <para>Connect the USB stick to the development machine and identify
          the device name given by the system with
          <command>lsblk</command>:
            <programlisting>NAME         MAJ:MIN          RM    SIZE    RO TYPE MOUNTPOINT
sda            8:0            1     28.7G   0  disk
sdb            8:0            0     111.8G  0  disk
|-sdb1         8:1            0     111.8G  0  part</programlisting></para>
        </listitem>

        <listitem>
          <para>Copy the HDDIMG image onto the USB stick, e.g:
            <programlisting>sudo dd if=./enea-nfv-access-&lt;machine&gt;.hddimg \
of=/dev/sdb bs=4M conv=fsync</programlisting></para>
        </listitem>
      </orderedlist>

      <para>Where <filename>enea-nfv-access-&lt;machine&gt;.hddimg
      </filename>is the <literal>.hddimg</literal> file and <literal>sdb</literal> is the
      assigned USB device name.</para>
    </section>

    <section id="install_ena_stick">
      <title>Installing Enea NFV Access</title>
      
      <para><emphasis role="bold">How to install the Enea NFV Access Run Time
      Platform using a bootable USB stick image</emphasis></para>

      <orderedlist>
        <listitem>
          <para>Plug the USB stick into the uCPE device. Connect a laptop directly into one of the ports that will
	  not later be chosen as a WAN port. No other ports should be connected.</para>
        </listitem>

        <listitem>
          <para>Power up the uCPE device and boot the USB stick. Verify that the
          USB stick is selected from the BIOS boot menu.</para>
        </listitem>

        <listitem>
          <para>Once the USB stick is properly booted, the Web-installer application starts
            automatically and can be accessed in a web browser at <literal>http://172.16.1.1</literal> (port 80).
	  </para>
          
          <para>On the first page of the Web-installer, the user should fill in:</para>

          <itemizedlist>
            <listitem>
              <para><emphasis role="bold">The uCPE Manager IP Address</emphasis>.</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">The Device ID</emphasis>. The unique identifier of the
	      uCPE device.</para>
	      
            </listitem>

            <listitem>
              <para><emphasis role="bold">Customer Tags</emphasis>. They are used for  
	      <link linkend="zero_touch_prov">Zero Touch Provisining (ZTP)</link> and can be left 
                empty. What can be entered here (as needed), are the tag(s) specified when 
                creating an offline configuration in the uCPE Manager.</para>
            </listitem>
          </itemizedlist>

          <para>On the second page of the Web-installer, the user should fill in:</para>

          <itemizedlist>	    
            <listitem>
              <para><emphasis role="bold">The Layer 3 configuration of WAN Interface(s)</emphasis>. 
                Static or Dynamic IP must be specified.</para>
              
              <para>During network configuration, WAN cables will be plugged into the device
	      in order to identify ports and make them available for configuration. Each 
              port with a physically connected cable will be automatically set as a WAN port and must be
	      configured (DHCP is the default setting). The user needs to connect the same quantity of 
                cables as the number of WAN ports that he wishes to configure. No LAN ports should be 
                connected nor configured at this time. The configured WAN cables cannot be removed 
                after being configured.</para>

	      <note>
		<para>The LAN port used to access the Web-installer from the laptop will not be shown
	      and cannot be configured.</para></note>      
            </listitem>

	    <listitem>
              <para><emphasis role="bold">The Management Interface</emphasis>. The interface that 
                will be used by the uCPE Manager to communicate with the device.</para>
              
	    </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>When the user has completed the configuration steps in the Web-installer, NFV Access
	  is installed on the hard drive. The largest drive found on the device will be used for
	  installation.</para>
        </listitem>
	
      </orderedlist>
    </section>

    <section id="boot_ena">
      <title>Booting NFV Access</title>

      <para>When the installation has finished successfully, the user should remove the USB stick 
      before confirming the reboot of the device in Web-installer and ensure that BIOS is configured
      to boot from the hard drive.</para>

      <para>When configured with the Web-installer GUI, the uCPE device start-up sequence will 
        configure the interfaces accordingly and try to register the device in the uCPE manager. 
        If connectivity is established with the uCPE manager server and a device with a matching 
        Device ID is found, the configuration is successful, and the connection is established.</para>
	      
      <note>
	<para>If NFV Access was installed by Bare Metal Provisioning, the Web-installer will launch at
	start-up expecting the user to provide the post-installation configuration. The Web-installer will
	be launched on port 80 for post-installation configuration: <literal>
        http://172.168.1.1</literal>.</para>
      </note>

      <para>In case of failure, the user should remove all WAN cables, re-attach the laptop, reboot 
        the device and then access the Web-installer on <literal>http://172.16.1.1</literal>.
      </para>
      
      <note>      
	<para>After having established a successful connection with the uCPE Manager, the user will 
        connect any LAN cable(s) that should be connected to the device.
	</para>
      </note>      
    </section>

    <section condition="hidden" id="examples">
      <title>Examples</title>

      <para>Below are a few examples of setups that the Enea NFV Access
      installer can be used for:</para>

      <itemizedlist>
        <listitem xreflabel="example_one">
          <para>Partitioning a drive:</para>

          <programlisting>set drive=/dev/sda
run</programlisting>
        </listitem>

        <listitem xreflabel="example_two">
          <para>Partitioning a drive, installing GRUB, and a Root
          Filesystem:</para>

          <programlisting>set drive=/dev/sda
set grub_destination=/dev/sda1
set grub_binary=/home/user/grub-binary.efi
set rootfs_destination=/dev/sda2
set rootfs_targz=/home/user/rootfs.tar.gz
run</programlisting>
        </listitem>

        <listitem xreflabel="example_three">
          <para>Deploying ONLY a root filesystem:</para>

          <programlisting>set rootfs_destination=/dev/sda2
set rootfs_targz=/home/user/rootfs.tar.gz
run</programlisting>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section condition="hidden" id="release-content">
    <title>NFV Access Release content</title>

    <para>The NFV Access 1.1 Release contains along with other items,
    documentation, pre-built kernels and images, a bootloader and a
    SDK.</para>

    <para>The directories structure is detailed below:</para>

    <programlisting>-- documentation/
   /* NFV Access documentation */
-- xeon-d/
   /* artifacts for the host side */
        -- deb/
           /* deb packages */
        -- images/
            -- enea-image-virtualization-host
               /* precompiled artifacts for the Host release image */
                -- various artifacts
            -- enea-image-virtualization-host-sdk
               /* precompiled artifacts for the Host SDK image.
               The SDK image contains userspace tools and kernel
               configurations necessary for developing, debugging
               and profiling applications and kernel modules */
                -- various artifacts
        -- sdk
           /* NFV Access SDK for the host */
                -- enea-glibc-x86_64-enea-image-virtualization-host-sdk /
                   -corei7-64-toolchain-7.0.sh
                   /* self-extracting archive installing
                   cross-compilation toolchain for the host */
-- qemux86-64
   /* artifacts for the guest side */
        -- deb/
           /* deb packages */
        -- images/
            -- enea-image-virtualization-guest
               /* precompiled artifacts for the Guest image */
                -- various artifacts
        -- sdk
           /* NFV Access SDK for the guest */
                -- enea-glibc-x86_64-enea-image-virtualization-guest-sdk /
                   -core2-64-toolchain-7.0.sh
                   /* self-extracting archive installing cross-compilation
                   toolchain for the guest (QEMU x86-64) */</programlisting>

    <para>For each combination of image and uCPE device, the following set of
    artifacts is available:</para>

    <programlisting>-- bzImage
   /* kernel image */
-- bzImage-&lt;target&gt;.bin
   /* kernel image, same as above */
-- config-&lt;target&gt;.config
   /* kernel configuration file */
-- core-image-minimal-initramfs-&lt;target&gt;.cpio.gz
   /* cpio archive of the initramfs */
-- core-image-minimal-initramfs-&lt;target&gt;.qemuboot.conf
   /* qemu config file for the initramfs image */
-- &lt;image-name&gt;-&lt;target&gt;.ext4
   /* EXT4 image of the rootfs */
-- &lt;image-name&gt;-&lt;target&gt;.hddimg
   /* msdos filesystem containing syslinux, kernel, initrd and rootfs image */
-- &lt;image-name&gt;-&lt;target&gt;.iso
   /* CD .iso image */
-- &lt;image-name&gt;-&lt;target&gt;.qemuboot.conf
   /* qemu config file for the image */
-- &lt;image-name&gt;-&lt;target&gt;.tar.gz
   /* tar archive of the image */
-- &lt;image-name&gt;-&lt;target&gt;.wic
   /* Wic image */
-- microcode.cpio
   /* kernel microcode data */
-- modules-&lt;target&gt;.tgz
   /* external kernel modules */
-- ovmf.*.qcow2
   /* ovmf firmware for uefi support in qemu */
-- rmc.db
   /* Central RMC Database */
-- systemd-bootx64.efi
   /* systemd-boot EFI file */
-- grub-efi-bootx64.efi
   /* GRUB EFI file */</programlisting>
  </section>

  <section condition="hidden" id="prebuilt-artifacts">
    <title>How to use the Prebuilt Artifacts</title>

    <section id="boot-ramdisk">
      <title>Booting Enea NFV Access using RAMDISK</title>

      <para>There may be use cases, especially at first target ramp-up, where
      the HDD/SDD has no partitions and you need to prepare the disks for
      boot. Booting from ramdisk can help with this task.</para>

      <para>The prerequisites needed to proceed:</para>

      <itemizedlist>
        <listitem>
          <para>Enea NFV Access ext4 rootfs image -
          enea-nfv-access-xeon-d.ext4.gz</para>
        </listitem>

        <listitem>
          <para>Enea NFV Access kernel image - bzImage</para>
        </listitem>

        <listitem>
          <para>BIOS has PXE boot enabled</para>
        </listitem>

        <listitem>
          <para>PXE/tftp server configured and connected (ethernet) to
          target.</para>
        </listitem>
      </itemizedlist>

      <para>Unzip enea-nfv-access-xeon-d.ext4 and copy bzImage and
      enea-nfv-access-xeon-d.ext4 images to the tftpserver configured for PXE
      boot.</para>

      <para>Use the following as an example for the PXE configuration
      file:</para>

      <programlisting>default vesamenu.c32
prompt 1
timeout 0

label el_ramfs
    menu label ^EneaLinux_RAMfs
    kernel bzImage
    append root=/dev/ram0 initrd=enea-nfv-access-xeon-d.ext4 /
    ramdisk_size=1200000 console=ttyS0,115200 eralyprintk=ttyS0,115200</programlisting>

      <para>Restart the target. Then enter (F11) in the Boot Menu and select
      the Ethernet interface used for PXE boot. From the PXE Boot Menu select
      <emphasis role="bold">Enea NFV Access_RAMfs</emphasis>. Once the Enea
      NFV Access is started you can partition the HDD/SDD and install GRUB as
      described in in the following section.</para>
    </section>

    <section id="install-grub">
      <title>Partitioning a new harddisk and installing GRUB</title>

      <para>The prerequisites needed:</para>

      <itemizedlist>
        <listitem>
          <para>grub (<literal>grub-efi-bootx64.efi</literal>) - availalble as
          a pre-built artifact under
          <literal>xeon-d/images/enea-nfv-access</literal>.</para>
        </listitem>

        <listitem>
          <para><literal>e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb,/</literal></para>

          <para><literal>dosfstools_4.1-r0.0_amd64.deb</literal> - available
          under <literal>xeon-d/deb</literal>.</para>
        </listitem>
      </itemizedlist>

      <para>Proceed using the following steps:</para>

      <orderedlist>
        <listitem>
          <para>Boot target with Enea NFV Access from RAMDISK</para>
        </listitem>

        <listitem>
          <para>Install prerequisite packages:</para>

          <programlisting>&gt; dpkg -i e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb
&gt; dpkg -i dosfstools_4.1-r0.0_amd64.deb</programlisting>
        </listitem>

        <listitem>
          <para>Partition the disk:</para>

          <programlisting>&gt; fdisk /dev/sda
fdisk&gt; g   {GPT partition type}
fdisk&gt; n
fdisk&gt; 1
fdisk&gt;     {default start part}
fdisk&gt; +512M
fdisk&gt; t
fdisk&gt; 1 {ESP/EFI partition}
fdisk&gt; n
fdisk&gt; 2
fdisk&gt;    {default start part}
fdisk&gt; +18G
fdisk&gt; 3
fdisk&gt;    {default start part}
fdisk&gt; +20G
...
fdisk&gt; 7
fdisk&gt;  {default start part}
fdisk&gt;  {default end end part}

fdisk&gt; p  {print partion table}
fdisk&gt; w   {write to disk}
fdisk&gt; q</programlisting>
        </listitem>

        <listitem>
          <para>Format the partitions:</para>

          <programlisting>&gt; mkfs.fat -F32 -nEFI /dev/sda1
&gt; mkfs.ext4 -LROOT /dev/sda2
&gt; mkfs.ext4 -LROOT /dev/sda3
&gt; mkfs.ext4 -LROOT /dev/sda4
&gt; mkfs.ext4 -LROOT /dev/sda5
&gt; mkfs.ext4 -LROOT /dev/sda6
&gt; mkfs.ext4 -LROOT /dev/sda7</programlisting>
        </listitem>

        <listitem>
          <para>Create a GRUB partition:</para>

          <programlisting>&gt; mkdir /mnt/boot
&gt; mount /dev/sda1 /mnt/boot
&gt; mkdir -p /mnt/boot/EFI/boot

&gt; cp grub-efi-bootx64.efi /mnt/boot/EFI/boot/bootx64.efi
&gt; vi /mnt/boot/EFI/boot/grub.cfg
default=1

menuentry "Linux Reference Image" {
  linux (hd0,gpt2)/boot/bzImage root=/dev/sda2 ip=dhcp
}

menuentry "Linux sda3" {
  linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp
}

menuentry "Linux sda4" {
  linux (hd0,gpt4)/boot/bzImage root=/dev/sda4 ip=dhcp
}

menuentry "Linux sda5" {
  linux (hd0,gpt5)/boot/bzImage root=/dev/sda5 ip=dhcp
}

menuentry "Linux sda6" {
  linux (hd0,gpt6)/boot/bzImage root=/dev/sda6 ip=dhcp
}

menuentry "Linux sda7" {
  linux (hd0,gpt7)/boot/bzImage root=/dev/sda7 ip=dhcp
}</programlisting>
        </listitem>
      </orderedlist>
    </section>

    <section id="boot-hdd">
      <title>Installing and booting Enea NFV Access on the harddisk</title>

      <para>After partitioning the harddisk, boot Enea NFV Access from RAMFS
      or from a reference image installed on one of the partitions.</para>

      <para>To install Enea NFV Access image on a partition follow these
      steps:</para>

      <orderedlist>
        <listitem>
          <para>Copy your image on target:</para>

          <programlisting>server&gt; scp ./enea-nfv-access-xeon-d.tar.gz /
root@&lt;target_ip&gt;:/home/root/</programlisting>
        </listitem>

        <listitem>
          <para>Extract image onto the desired partition:</para>

          <programlisting>target&gt; mount /dev/sda3 /mnt/sda
target&gt; tar -pzxf /home/root/enea-nfv-access-xeon-d.tar.gz /
-C /mnt/sda</programlisting>

          <para>Alternately, you can do both steps in one command from the
          server:</para>

          <programlisting>server&gt; cat ./enea-nfv-access-xeon-d.tar.gz | /
ssh root@&lt;target_ip&gt; "cd /mnt/sda6; tar -zxf -"</programlisting>
        </listitem>

        <listitem>
          <para>Reboot</para>
        </listitem>

        <listitem>
          <para>From the GRUB menu select your partition</para>
        </listitem>
      </orderedlist>

      <note>
        <para>In order to change kernel boot parameters you need to mount the
        GRUB partition (i.e. <literal>/dev/sda1</literal>) and change the
        <literal>EFI/boot/grub.cfg</literal> file.</para>
      </note>
    </section>
  </section>
</chapter>