path: root/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.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="advanced_conf">
  <title>Advanced Configurations</title>

  <para>This chapter describes possible configurations for select advanced
  features such as the Hugepage Reservation Service, UEFI Secure Boot and Bare
  Metal Provisioning. These features are optional in the Enea NFV Access
  platform. If you do not intend to use these features, skip this
  chapter.</para>

  <section id="hugepage_reservation">
    <title>Hugepage Reservation Service</title>

    <para>NFV Access implements an automatic hugepage allocation service that
    is triggered at each startup. The service is skipped if hugepages have
    been allocated in the kernel boot command line.</para>

    <para>There are two strategies outlined for hugepage allocation:</para>

    <itemizedlist>
      <listitem>
        <para>If a system has an amount of memory up to 8GB, the allocation
        algorithm will reserve up to 30% (no more than 2GB), for the OS and
        the rest as 2MB hugepages.</para>
      </listitem>

      <listitem>
        <para>If a system has an amount of memory that's higher than 8GB, the
        allocation algorithm will reserve all but 2GB of memory as 1GB
        hugepages, leaving the rest (2GB) to be used by the OS.</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>This is a best effort reservation after kernel boot, so the
      results may vary accordingly.</para>
    </note>

    <section id="hugepage_customizing_auto">
      <title>Customizing Automatic Hugepage Reservation</title>

      <para>Configuration of Hugepage reservation is done in
      <literal>/etc/enea-nfv-access/hugepages.cfg</literal>.</para>

      <para><emphasis role="bold">Parameters used by the automatic algorithm:
      </emphasis></para>

      <itemizedlist spacing="compact">
        <listitem>
          <para><literal>hugepage_setup</literal>: Enables the automatic
          configuraiton algorithm. It has only one value,
          <literal>auto</literal>. For manual configuration comment or remove
          this parameter. Use the other parameter descriptions as a
          template/example.</para>
        </listitem>

        <listitem>
          <para><literal>threshold_to_use_1g</literal>: Decides the threshold
          which instructs the algorithm to use 1GB hugepages. If a system's
          memory is higher than <literal>threshold_to_use_1g</literal>, then
          the algorithm will use 1GB hugepages, otherwise it will use 2MB
          hugepages.</para>
        </listitem>

        <listitem>
          <para><literal>percent_os_alloc</literal>: Decides how much memory
          to try to reserve for userspace applications. The algorithm will try
          to reserve at least the value of <literal>percent_os_alloc</literal>
          of the total system memory for userspace applications.</para>
        </listitem>

        <listitem>
          <para><literal>maximum_os_alloc_mb</literal>: Maximum amount of
          memory to allocate for userspace applications. If
          <literal>percent_os_alloc</literal> of the total system memory
          exceeds <literal>maximum_os_alloc_mb</literal> then the maximum
          allocated memory for userspace applications is
          <literal>maximum_os_alloc_mb</literal>.</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">Example of automatic Hugepage
      Configuration:</emphasis></para>

      <programlisting> hugepage_setup = auto
 threshold_to_use_1g = 8192
 percent_os_alloc = 30
 maximum_os_alloc_mb = 2048</programlisting>

      <para>The following possible allocations can result (based on total
      system memory available):</para>

      <itemizedlist>
        <listitem>
          <para>2GB of memory: approximately 30% will be allocated for the OS
          and the rest will be allocated as 2MB hugepages.</para>
        </listitem>

        <listitem>
          <para>4GB of memory: approximately 30% will be allocated for the OS
          and the rest will be allocated as 2MB hugepages.</para>
        </listitem>

        <listitem>
          <para>16GB of memory: approximately 2GB will be allocated for the OS
          and the rest as 1GB hugepages.</para>
        </listitem>
      </itemizedlist>

      <note>
        <para>The memory allocated for the kernel and hugepages might vary
        slightly depending on how much memory is available.</para>
      </note>
    </section>

    <section id="hugepage_customizing_man">
      <title>Customizing Manual Hugepage Reservation</title>

      <para>The automatic algorithm can be disabled and hugepages in turn,
      configured manually. To do this, comment the line which defines
      <literal>hugepage_setup</literal> as <literal>auto</literal> and
      configure memory for each CPU socket in the following manner:</para>

      <programlisting>&lt;NUMA node&gt;.&lt;hugepage size&gt; = &lt;number of pages&gt;</programlisting>

      <para>Where <literal>&lt;NUMA node&gt;</literal> refers to a node which
      is part of the system's NUMA topology, <literal>&lt;hugepage
      size&gt;</literal> decides what type of hugepages should be set and
      <literal>&lt;number of hugepages&gt;</literal> is how many hugepages of
      <literal>&lt;hugepage size&gt;</literal> should be allocated.</para>

      <para>To list the available system nodes, run:</para>

      <programlisting>ls -d /sys/devices/system/node/node* </programlisting>

      <para>To list available hugepage sizes, per node, run:</para>

      <programlisting>ls -d /sys/devices/system/node/node*/hugepages/hugepages-*</programlisting>

      <para>Example of Manual Hugepage Configuration, configuring the system
      to allocate three 1GB hugepages and 512 of 2MB hugepages on node:</para>

      <programlisting>node0.2048kB = 512
node0.1048576kB = 3 </programlisting>

      <note>
          <para>Make sure there are no hugepages reserved in the kernel boot
              command line, these will override any manual configuration done
              in the service.</para>
      </note>
    </section>
  </section>

  <section id="uefi_secure_boot">
    <title>UEFI Secure Boot</title>

    <para>Secure Boot was designed to enhance security in the pre-boot
    environment. It prevents malicious software and applications from being
    loaded during the system start-up process.</para>

    <para>The basic principle of UEFI Secure Boot is that it requires all
    artifacts involved in the boot process (bootloaders, kernel, initramfs) to
    be signed using a set of private keys. On a Secure Boot enabled uCPE
    device these artifacts are checked against a set of public certificates
    which correspond to these keys. If there are any mismatches the boot
    process will fail at the stage(s) they are detected.</para>

    <para>For more information about Secure Boot please refer to <ulink
    url="https://www.uefi.org/sites/default/files/resources/UEFI_Secure_Boot_in_Modern_Computer_Security_Solutions_2013.pdf">Secure
    Boot in Modern Computer Security Solutions</ulink>.</para>

    <section id="secure_boot_keys">
      <title>Enabling UEFI Secure Boot</title>

      <para>All Enea NFV Access image artifacts delivered with the release are
      signed using the Enea UEFI Secure boot private keys. These artifacts can
      be used on a uCPE device that doesn't have Secure Boot enabled. To use
      the Secure Boot feature, however, the user must make the Enea UEFI
      Secure Boot public certificates available on the uCPE device before
      enabling the feature in BIOS. This process is called
      "Provisioning".</para>

      <section id="manual_key_provisioning">
        <title>Provisioning the Enea UEFI Secure Boot Certificates</title>

        <para>The UEFI firmware is normally shipped with factory preloaded
        certificates. If these do not already include Certificates from Enea,
        they will need to be appended or replaced with the Enea
        Certificates.</para>

        <para><emphasis role="bold">UEFI Secure Boot certificates provided
        with your release:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para><literal>Platform Key (PK)</literal>: this key protects the
            next key from uncontrolled modification. Once this key is
            enrolled, Secure Boot enters into <literal>User Mode</literal>.
            The drivers and loaders signed with the <literal>Platform
            Key</literal> can then be loaded by the firmware.</para>
          </listitem>

          <listitem>
            <para><literal>Key Exchange key (KEK)</literal>: this key allows
            other certificates which have a connection to the private portion
            of the <literal>Platform Key</literal> to be used.</para>
          </listitem>

          <listitem>
            <para><literal>Authorized Signature (DB)</literal>: contains the
            <literal>trusted keys</literal> used for authenticating any
            drivers or applications executed in the UEFI environment.</para>
          </listitem>
        </itemizedlist>

        <para>The Enea UEFI Secure Boot certificates are installed together
        with the Enea NFV Access Run Time Platform onto the hard drive. They
        can be found on the EFI partition (usually the first partition of the
        drive) under <literal>/uefi_sb_keys</literal>.</para>

        <para>These certificates need to be manually enrolled in BIOS. The
        exact details on how to proceed may vary depending the version of the 
          UEFI firmware.</para>
      </section>

      <section id="enable_secure_boot">
        <title>Enabling Secure Boot in BIOS</title>

        <para>Once the certificates are enrolled, Secure Boot needs to be
        enabled in BIOS and the device rebooted.</para>
      </section>
    </section>
  </section>

  <section id="bare_meta_prov">
    <title>Bare Metal Provisioning</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 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 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
          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_server">
      <title>Server Configuration</title>

      <para>The following images provided with your Enea NFV Access release
      need to be made available on the PXE and HTTP servers:</para>

      <orderedlist>
        <listitem>
          <para>Copy the Enea NFV Access installer
          <literal>initramfs</literal> image and kernel
          <literal>bzImage</literal> for your uCPE device architecture to the
          TFTP directory on the PXE server (e.g
          <literal>/var/lib/tftpboot</literal>).</para>
        </listitem>

        <listitem>
          <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>
      </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. This
            image will be installed on the uCPE device(s) in the
            <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 <literal>Server
            IP:directory</literal> 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 install config file&gt;
	ipappend 2
    </programlisting>
      </section>
    </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 require
      vendor-specific tools.</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>
        <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 Run Time
        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.</para>

        <note>
          <para>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>
        </note>
      </section>
    </section>
  </section>
</chapter>