path: root/doc/book-enea-nfv-access-guide/doc/getting_started.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 ENFV Access</title>

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

    <para>The NFV Access 1.0 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 */
-- inteld1521/
   /* 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 target, 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 id="docs">
    <title>Included Documention</title>

    <para>Enea NFV Access is provided with the following set of
    documents:</para>

    <itemizedlist>
      <listitem>
        <para>Enea NFV Access Guide &ndash; A document describing the Enea NFV
        Access release content and how to use it, as well as benchmark
        results.</para>
      </listitem>

      <listitem>
        <para>Enea NFV Access Open Source Report &ndash; A document containing
        the open source and license information pertaining to packages
        provided with Enea NFV Access 1.0.</para>
      </listitem>

      <listitem>
        <para>Enea NFV Access Test Report &ndash; The document that summarizes
        the test results for the Enea NFV Access release.</para>
      </listitem>

      <listitem>
        <para>Enea NFV Access Security Report &ndash; The document that lists
        all security fixes included in the Enea NFV Access 1.0 release.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section 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-image-virtualization-host-inteld1521.ext4</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>Copy bzImage and enea-image-virtualization-host-inteld1521.ext4.gz
      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-image-virtualization-host-inteld1521.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>inteld1521/images/enea-image-virtualization-host</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>inteld1521/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-image-virtualization-host-inteld1521.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-image-virtualization-host-inteld1521.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-image-virtualization-host-inteld1521.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>