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

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="getting_started_ucpe_manager">
  <title>Getting Started with Enea uCPE Manager</title>

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

    <para>Listed below are the main generic prerequisites required so that the
    uCPE Manager can be deployed on the host platform:</para>

    <itemizedlist>
      <listitem>
        <para>A uCPE device with Enea NFV Access Run Time Platform
        installed.</para>
      </listitem>

      <listitem>
        <para>A machine running CentOS 7 with network access to the physical
        device.</para>
      </listitem>

      <listitem>
        <para>CPU, RAM and storage requirements for the uCPE Manager:</para>

        <itemizedlist>
          <listitem>
            <para>For small-sized deployments (tens of devices):</para>

            <itemizedlist spacing="compact">
              <listitem>
                <para>4 cores</para>
              </listitem>

              <listitem>
                <para>16 GB RAM</para>
              </listitem>

              <listitem>
                <para>300 GB hard-drive</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>For mid-sized deployments (hundreds of devices):</para>

            <itemizedlist spacing="compact">
              <listitem>
                <para>8 cores</para>
              </listitem>

              <listitem>
                <para>32 GB RAM</para>
              </listitem>

              <listitem>
                <para>300 GB hard-drive</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>For large deployments (thousands of devices):</para>

            <itemizedlist spacing="compact">
              <listitem>
                <para>16 cores</para>
              </listitem>

              <listitem>
                <para>64-256 GB RAM</para>
              </listitem>

              <listitem>
                <para>1 - 2 TB hard-drive</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
  </section>

  <section id="install_ucpe_manager">
    <title>Install the Enea uCPE Manager</title>

    <para>Unpack the uCPE Manager and install it following the instructions
    below.</para>

    <section id="prep_sys_ucpe_mg">
      <title>Preparing your system</title>

      <orderedlist>
        <listitem>
          <para>Install Java:</para>

          <orderedlist>
            <listitem>
              <para>Install OpenJDK 11:</para>

              <programlisting>sudo yum install java-11-openjdk-devel</programlisting>
            </listitem>

            <listitem>
              <para>Verify the installation:</para>

              <programlisting>java -version

openjdk version "11.0.3" 2019-04-16 LTS
OpenJDK Runtime Environment 18.9 (build 11.0.3+7-LTS)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing)</programlisting>
            </listitem>

            <listitem>
              <para>The following system variables need to point to the
              OpenJDK 11 installation:</para>

              <programlisting>export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which javac)))))
export PATH=$PATH:$JAVA_HOME/bin
export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar
</programlisting>
            </listitem>
          </orderedlist>

          <note>
            <para>If there are multiple java versions installed, switch
            between them using the following command:</para>

            <programlisting>alternatives --config java</programlisting>
          </note>
        </listitem>

        <listitem>
          <para>Open a terminal with administrative rights, i.e. log into a
          <emphasis role="bold">bash</emphasis> shell with
          <literal>root</literal> privileges.</para>
        </listitem>

        <listitem>
          <para>Choose the target installation folder, e.g.
          <literal>/opt/ems</literal>. Everything will be installed under a
          folder called <literal>ucpemanager</literal> within the target
          installation folder.</para>
        </listitem>
      </orderedlist>

      <para>The application files will be installed in
      <literal>/opt/ems/ucpemanager/application</literal>. The database will
      be installed in <literal>/opt/ems/ucpemanager/database</literal>.</para>

      <note>
        <para>If you have multiple spindles, it is recommended to let the
        application run off one and the database off the other. This will
        result in optimum performance. It is also recommended that the swap
        disk be the same as the one used for the application.</para>
      </note>

      <para>Assuming another spindle is used (<literal>/drive2</literal>) do
      the following:</para>

      <itemizedlist>
        <listitem>
          <para>Create a folder which will host the database (e.g.
          <literal>emsDatabase</literal>).</para>
        </listitem>

        <listitem>
          <para>Create a soft-link that will point to this folder:</para>

          <programlisting>ln -s /opt/ems/elementcenter/database /drive2/emsDatabase</programlisting>
        </listitem>

        <listitem>
          <para>Follow the installation process as described below.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="installing_ucpe_mg">
      <title>Installing the uCPE Manager</title>

      <orderedlist>
        <listitem>
          <para>Open a terminal with administrative rights, i.e. log into a
          <emphasis role="bold">bash</emphasis> shell with
          <literal>root</literal> privileges.</para>
        </listitem>

        <listitem>
          <para><command>cd</command> to the folder you are installing
          from.</para>
        </listitem>

        <listitem>
          <para>Verify that the folder you are installing from contains the
          following files:</para>

          <itemizedlist>
            <listitem>
              <para><filename>README</filename></para>
            </listitem>

            <listitem>
              <para><filename>install.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>doinstall.sh</filename></para>
            </listitem>

            <listitem>
              <para><literal>configureHA.sh</literal></para>
            </listitem>

            <listitem>
              <para><filename>ucpemanager-x.y-Buildz-Linux.tar.gz</filename></para>
            </listitem>

            <listitem>
              <para><filename>ReleaseNotes</filename></para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Run the following command:</para>

          <programlisting>./install.sh /opt/ems ucpemanager-x.y-Buildz-Linux.tar.gz</programlisting>
        </listitem>
      </orderedlist>

      <para>This command will:</para>

      <itemizedlist>
        <listitem>
          <para>Extract the application files from the compressed install
          kit.</para>
        </listitem>

        <listitem>
          <para>Install the bundled database (if the user specifies an
          internal database).</para>
        </listitem>

        <listitem>
          <para>Install <literal>ucpemanager</literal> as a service with the
          name <filename>ucpemanager</filename>.</para>
        </listitem>

        <listitem>
          <para>Start the <literal>ucpemanager</literal> service.</para>
        </listitem>
      </itemizedlist>

      <note>
        <para>The service will be automatically started when the computer
        boots up. The user may enable the firewall in order to allow access to
        these specific ports: 80 (TCP), 443 (TCP), 54327 (UDP) and 5701:5708
        (TCP). If callhome is used access to the following ports must also be
        allowed: 4334 (TCP) and 2021:2040 (TCP). Otherwise, the user should
        check that the CentOS machine where the uCPE Manager is installed has
        the firewall disabled.</para>
      </note>

      <para>Verify that the installation has succeeded by:</para>

      <orderedlist>
        <listitem>
          <para>Pointing your browser to the server machine running the uCPE
          Manager.</para>
        </listitem>

        <listitem>
          <para>In the login screen, log in with the username: <emphasis
          role="bold">admin</emphasis> and password: <emphasis
          role="bold">admin</emphasis>.</para>
        </listitem>
      </orderedlist>

      <para>In order to manage the ucpemanager service, user can run:
      <programlisting>service ucpemanager start/stop</programlisting></para>
    </section>

    <section id="ins_restore_option">
      <title>Installing with the restore option</title>

      <para>It is possible to use a restore file created by the "System
      Backup" utility provided in the uCPE Manager, to install a system and
      set it to a known state.</para>

      <note>
        <para>The file to be used is the zip file created by System Backup,
        not the one created by the uninstall or upgrade processes described
        below.</para>
      </note>

      <para>The name format of this file will be:
      <filename>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</filename> (e.g
      <literal>SystemBackup_Feb19_2013_2257_42.zip</literal>).</para>

      <para>Follow the steps for Installation provided above and provide an
      additional argument as shown below:</para>

      <programlisting>./install.sh \
      /opt/ems ucpemanager-1.0-Build8-Linux.tar.gz  \
      SystemBackup_MMMDD_YYYY_HHMM_SS.zip</programlisting>

      <para>The other steps are exactly the same as specified in the
      Installation instructions.</para>
    </section>

    <section id="upgrading_ucpe_mg">
      <title>Upgrading the uCPE Manager</title>

      <orderedlist>
        <listitem>
          <para>Verify that the folder you are upgrading from contains the
          following files:</para>

          <itemizedlist>
            <listitem>
              <para><filename>upgrade.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>doupgrade.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>configureHA.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>ucpemanager-x.y-Buildz-Linux.tar.gz</filename></para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Run the following command:</para>

          <programlisting>./upgrade.sh /opt/ems ucpemanager-1.0-Build8-Linux.tar.gz</programlisting>
        </listitem>
      </orderedlist>

      <para>Running this command will:</para>

      <itemizedlist>
        <listitem>
          <para>Stop the currently running ucpemanager service.</para>
        </listitem>

        <listitem>
          <para>Create a compressed file of the ucpemanager application
          folder, called:
          <literal>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</literal>, which
          contains a snapshot of the existing installation.</para>
        </listitem>

        <listitem>
          <para>Rename the <literal>application</literal> folder to
          <literal>application_original</literal>.</para>
        </listitem>

        <listitem>
          <para>Extract the application files from the specified compressed
          install kit. There will now exist a (new) application folder, with
          the contents of the new kit.</para>
        </listitem>

        <listitem>
          <para>Start the ucpemanager service.</para>
        </listitem>
      </itemizedlist>

      <para>When the ucpemanager service starts, it will recognize the fact
      that an old version of the application needs to be upgraded (based upon
      the existence of the <literal>application_original</literal> folder. All
      the relevant data from the old installation will be copied to the new
      one and the <literal>application_original</literal> folder will be
      deleted.</para>
    </section>

    <section id="uninstalling_ucpe_mg">
      <title>Uninstalling an existing uCPE Manager installation</title>

      <orderedlist>
        <listitem>
          <para>Verify that the folder you are uninstalling from contains the
          following files:</para>

          <itemizedlist>
            <listitem>
              <para><filename>uninstall.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>douninstall.sh</filename></para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Run the following command:</para>

          <programlisting>./uninstall.sh /opt/ems</programlisting>
        </listitem>
      </orderedlist>

      <para>Running this command will:</para>

      <itemizedlist>
        <listitem>
          <para>Stop the currently running ucpemanager service.</para>
        </listitem>

        <listitem>
          <para>Create a compressed file of the ucpemanager application
          folder, called
          <literal>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</literal>, which
          contains a snapshot of the existing installation.</para>
        </listitem>

        <listitem>
          <para>Uninstall the ucpemanager service, so that it will not startup
          on reboot.</para>
        </listitem>

        <listitem>
          <para>Uninstall the database service (if an internal database is
          being used).</para>
        </listitem>

        <listitem>
          <para>Completely remove the contents of the
          <literal>application</literal> and <literal>database</literal>
          folders.</para>
        </listitem>
      </itemizedlist>

      <para>After these steps, the uCPE Manager is completely removed from the
      system.</para>
    </section>

    <section id="restoring_pre_installation">
      <title>Restoring a previous uCPE Manager installation</title>

      <orderedlist>
        <listitem>
          <para>Verify that the folder you are restoring from contains the
          following files:</para>

          <itemizedlist>
            <listitem>
              <para><filename>restore.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>dorestore.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>configureHA.sh</filename></para>
            </listitem>

            <listitem>
              <para><filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>
              (the original installation snapshot, as obtained from a previous
              uninstall).</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Run the following command:</para>

          <programlisting>./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz</programlisting>
        </listitem>
      </orderedlist>

      <para>Running this command will remove any vestiges of the existing
      ucpemanager service, if they exist, and reinstall the ucpemanager
      application on the specified target, restoring the data in the database
      and files in the process.</para>

      <para>The ucpemanager service is then started and the older version is
      now running on the system.</para>
    </section>
  </section>

  <section id="device_config_provision">
    <title>Device Configuration and Provisioning</title>

    <para>The following describes the steps required for setting up the
    virtualization infrastructure, ensuring that a uCPE device is ready for
    virtualized service deployment. The sections herein contain information
    about enrolling uCPE devices into the Enea uCPE Manager, selecting
    physical interfaces to be used by virtualized networking and creating
    different types of bridges to enable VNF communication. The Zero Touch
    Provisioning mechanism is also touched upon, as alternative to manual
    configuration of the virtualization infrastructure.</para>

    <section id="device_config">
      <title>Add a uCPE device to the Management System</title>

      <para>Enrolling uCPE devices into the Enea uCPE Manager can be
      accomplished using one of the two possible methods.</para>

      <section id="man_config">
        <title>Direct Connection</title>

        <para>When using this mechanism, the uCPE Manager will periodically
        poll the uCPE device, using a specified IP address as the destination,
        attempting to establish a management connection.</para>

        <para>Add the uCPE device running the NFV Access Run Time Platform to
        the management system by:</para>

        <orderedlist>
          <listitem>
            <para>Selecting in the uCPE Manager: <literal>Devices -&gt; Manage
            -&gt; Add</literal>.</para>
          </listitem>

          <listitem>
            <para>Suppling information about the uCPE device, and setting the
            parameters that will be used to connect to it.</para>
          </listitem>
        </orderedlist>

        <para>The relevant parameters are:</para>

        <itemizedlist>
          <listitem>
            <para>Type. The type of device to be added, i.e <literal>Enea
            universal CPE</literal>.</para>
          </listitem>
 
           <listitem>
            <para>Name. The name by which the device is referred to in the
            uCPE Manager.</para>
          </listitem>
 
          <listitem>
            <para>SSH Port. The NETCONF Port used for communications. Default
            is set to 830.</para>
          </listitem>

          <listitem>
            <para>SSH User Name. The user name for SSH connectivity. Default
            user is root.</para>
          </listitem>

          <listitem>
            <para>SSH Password. Leave this blank.</para>
          </listitem>

          <listitem>
            <para>Device Calls Home. This checkbox indicates the direction of
            device communications. For Direct Connection, leave this flag
            unchecked.</para>
          </listitem>

          <listitem>
            <para>Device ID. The unique identifier of the uCPE device.</para>
          </listitem>
        </itemizedlist>
      </section>

      <section id="using_call_home">
        <title>Device Call Home Connection</title>

        <para>Follow the same steps as described in the previous section,
        making sure that the <literal>Device Calls Home</literal> checkbox is
        selected this time.</para>

        <para>When using this mechanism, the device will initiate a connection
        to the uCPE Manager for NETCONF traffic (over SSH), while the uCPE
        Manager waits for a device connection. For more information please see
        section <link linkend="install_ena_stick">Installing Enea NFV
        Access</link> for more details.</para>
      </section>
    </section>

    <section id="host_int_net_config">
      <title>Configure NFV Infrastructure</title>

      <para>Once a management connection with the uCPE device has been
      established by using any of the supported methods, the virtualization
      networking infrastructure can be configured either manually or by using
      Zero Touch Provisioning.</para>

      <para>Available network interfaces can be added to the management
      system, for use by the networking virtualization infrastructure.</para>
      
          <para>In order to make physical network interfaces available to the
          virtualization infrastructure and VNFs, they must be configured into
          the management system.</para>

          <para>To add an interface into the uCPE Manager, select the uCPE
          device, then from the top toolbar select <literal>Configuration
          -&gt; External Interfaces -&gt; Configuration -&gt; Add</literal>. The available
          Interface types are detailed below.</para>

          <section id="dpdk_interface_type">
            <title>DPDK Interface Type</title>

            <para>Configuring a physical interface in DPDK mode will require a
            DPDK-based application (e.g. OVS-DPDK) in order to access and use
            the interface. An interface set as the DPDK can be attached to an
            OVS-DPDK bridge.</para>

            <note>
              <para>Make sure the <literal>Enable DPDK</literal> checkbox is
              selected in <literal>Device -&gt; Configuration -&gt;
              DPDK</literal>, otherwise no interface can be assigned to the
              DPDK.</para>
            </note>

            <para>To add a DPDK interface under the management system, set
            appropriate values for the following fields:</para>

            <itemizedlist>
              <listitem>
                <para>Source: name of the physical interface.</para>
              </listitem>

              <listitem>
                <para>Type: dpdk</para>
              </listitem>

              <listitem>
                <para>Networking-type: dpdk</para>
              </listitem>

              <listitem>
                <para>Dpdk-type: the kernel module that allows user space
                access to the physical interface. The <literal>vfio-pci</literal> 
                  driver is used.</para>
              </listitem>
            </itemizedlist>
          </section>

          <section id="sriov_interface_type">
            <title>SR-IOV Interface Type</title>

            <para>SR-IOV technology allows for the creation of a number of
            virtual functions on the host interface, which can be used by VNFs
            running on the uCPE device.</para>

            <para>For SR-IOV mode configuration, the user must set values for
            the following fields:</para>

            <itemizedlist>
              <listitem>
                <para>Source: name of the physical interface.</para>
              </listitem>

              <listitem>
                <para>Type: sr-iov</para>
              </listitem>

              <listitem>
                <para>Networking-type: srIov</para>
              </listitem>

              <listitem>
                <para>sriov-mode: adapter-pool</para>
              </listitem>

              <listitem>
                <para>sriov-num-vfs: the number of virtual functions to
                create.</para>
              </listitem>
            </itemizedlist>
          </section>

          <section id="standard_interface_type">
            <title>Standard Interface Type</title>

            <para>Some of the physical network interfaces available on a uCPE
            device, including Ethernet interfaces, do not have DPDK or SR-IOV
            support. Instead, the Linux kernel driver has to be used. Wi-Fi
            and 4G/LTE modems can also be configured and used for
            virtualization infrastructure and VNFs.</para>

            <para>To add Standard interfaces under the management system, the
            user must set values for the following fields:</para>

            <itemizedlist>
              <listitem>
                <para>Source: the name of physical interface.</para>
              </listitem>

              <listitem>
                <para>Networking-type: standard</para>
              </listitem>
            </itemizedlist>
          </section>

          <section condition="hidden" id="pci_passthrough_interface_type">
            <title>PCI Passthrough Interface Type</title>

            <para>For the PCI Passthrough a user does not have to configure a
            physical interface, instead simply select the PCI address and
            connect it to a virtual port when the VNF instantiation step is
            reached.</para>
          </section>

      <section id="man_configuration">
        <title>Manual Configuration</title>

        <para>For Manual Configuration of uCPE networking, select the uCPE
        device first and then <literal>Configuration</literal> -&gt;
        <literal>External Interfaces</literal>, where one can find a list of
        available network interfaces and their capabilities.</para>

        <section id="configure_interfaces">
          <title>Configuring Interfaces</title>

          <para>After networking interfaces have been added to the uCPE
          Manager, the user can change the interface type (DPDK, SR-IOV,
          Standard, WAN).</para>
            
            <note><para>WAN interfaces, which are configured during the 
            installation of the device, do not need to be added, they will 
              be automatically listed as such in the uCPE manager when the 
              device connects.</para></note>
          
          <figure>
                <title>Configuration of External Interfaces</title>

                <mediaobject>
                  <imageobject>
                    <imagedata align="center" contentwidth="600"
                               fileref="images/edit_inter_config.png" />
                  </imageobject>
                </mediaobject>
              </figure>

          <para><emphasis role="bold">How to Edit the Configuration of an
          Interface</emphasis></para>

          <orderedlist>
            <listitem>
              <para>To edit an interface configuration type from the uCPE
              Manager, select the uCPE device, then from the top toolbar
              select the <literal>Configuration</literal> menu then
              <literal>External Interfaces -&gt; Configuration</literal>. The
              already configured interfaces are displayed here, as can be seen
              in the figure above.</para>
            </listitem>

            <listitem>
              <para>In order to edit an already configured interface, (as in 
                the example popup shown below, a WAN interface) double click 
                on the desired one and a popup will appear. A different popup
                appears for each type of interface. From the Host Interface window, a user can 
                change the networking type and the IP address assignment:</para>

              <figure>
                <title>Editing an Interface</title>

                <mediaobject>
                  <imageobject>
                    <imagedata align="center" contentwidth="500"
                               fileref="images/edit_inter.png" />
                  </imageobject>
                </mediaobject>
              </figure>
            </listitem>
          </orderedlist>

          <note>
            <para>The IP address assignment of an interface can be set as
            static or dynamic for each type of interface.</para>
          </note>
        </section>

        <section id="configure_bridges">
          <title>Configuring Bridges</title>

          <para>After networking interfaces have been added to the uCPE
          Manager, the user can create the necessary OVS bridges.</para>

          <figure>
            <title>OVS Bridges</title>

            <mediaobject>
              <imageobject>
                <imagedata align="center" contentwidth="600"
                           fileref="images/ovs_bridges_tab.png" />
              </imageobject>
            </mediaobject>
          </figure>

          <para><emphasis role="bold">How to add OVS bridges in the uCPE
          Manager</emphasis></para>

          <orderedlist>
            <listitem>
              <para>Select the uCPE device.</para>
            </listitem>

            <listitem>
              <para>Select Configuration.</para>
            </listitem>

            <listitem>
              <para>Click OpenvSwitch.</para>
            </listitem>

            <listitem>
              <para>Select the Bridges option, then click Add.</para>
            </listitem>
          </orderedlist>

          <note>
            <para>Depending on the settings in <literal>Configuration -&gt;
            OpenVSwitch -&gt; DPDK</literal>, OVS bridges with or without DPDK
            support will be used on the uCPE device.</para>
          </note>

          <para>There are three types of bridges which can be created, each
          one fulfiling a different role.</para>

          <section id="inband_mg_bridge">
            <title>uCPE In-band Management bridge</title>

            <para>In-band Management refers to a model where both the data
            plane and control plane flow over the same network path. In some
            situations (e.g. the uCPE device has only one routable IP
            address), this is the only option available to both control and
            configure the uCPE device, while also allowing for data-path
            traffic to pass over the same physical interface.</para>

            <para>The solution provided by Enea for in-band management is
            based upon an OpenvSwitch bridge fielding all traffic passing
            through the WAN physical port. Any standard
            or DPDK-assigned network interface can be used for the In-Band
            management bridge.</para>

            <note>
              <para>The In-Band Management bridge must be recreated each time
              the uCPE Manager IP address is changed.</para>
            </note>

            <para>To create the In-Band Management bridge, the user must set
            values for the following fields:</para>

            <itemizedlist>
              <listitem>
                <para>name: name of the bridge.</para>
              </listitem>

              <listitem>
                <para>ovs-bridge-type: inbandMgmt</para>
              </listitem>
            </itemizedlist>

            <note>
              <para>The first VNF instantiated on the uCPE device must be
              connected to the In-Band Management bridge and its WAN interface
              must be configured as the DHCP client.</para>
            </note>
          </section>

          <section id="inband_mg_br_vnfs">
            <title>In-band Management bridge for VNFs</title>

            <para>If VNF management can be done over a dedicated virtual
            interface, its possible to extend the networking infrastructure
            configuration to also access the VNF's management interface over
            the WAN port.</para>

            <para>For this setup, three types of traffic will pass over the
            WAN physical interface:</para>

            <itemizedlist>
              <listitem>
                <para>Device management. Part of the device configuration done
                by the uCPE Manager.</para>
              </listitem>

              <listitem>
                <para>VNF(s) management. Enabling or disabling features of a
                VNF. E.g. enabling/disabling the firewall or VPN setup.</para>
              </listitem>

              <listitem>
                <para>Data-path. All other traffic that is not used in the
                control plane and needs to reach a LAN network.</para>
              </listitem>
            </itemizedlist>

            <para>To create a VNF In-Band Management bridge, the user must set
            values for the following fields:</para>

            <itemizedlist>
              <listitem>
                <para>name: name of the bridge.</para>
              </listitem>

              <listitem>
                <para>ovs-bridge-type: vnfMgmt</para>
              </listitem>

              <listitem>
                <para>vnf-mgmt-address: select IPv4 as the type and fill in
                the IP address for management network, e.g 10.0.0.1.</para>
              </listitem>
            </itemizedlist>

            <note>
              <para>VNF management interfaces must be configured in same
              network as the <literal>vnf-mgmt-address</literal> of the
              bridge. For more information, please see 4.4 <link
              linkend="vnf_management">VNF Management</link>.</para>
            </note>
          </section>

          <section id="dataplane_bridge">
            <title>Data-plane Bridge</title>

            <para>Data-plane bridges are generic bridges used for the VNF
            data-plane. There are two supported sub-types:</para>

            <itemizedlist>
              <listitem>
                <para>communication: allows for VNF communication towards
                LAN/WAN networks. This bridge type has at least one physical
                port attached to it.</para>
              </listitem>

              <listitem>
                <para>integration: allows for VNF-to-VNF communication
                (usually for service function chaining). This bridge type does
                not have any physical port attached.</para>
              </listitem>
            </itemizedlist>

            <para>To create a Data-plane bridge, the user must set values for
            the following fields:</para>

            <itemizedlist>
              <listitem>
                <para>name: name of the bridge.</para>
              </listitem>

              <listitem>
                <para>ovs-bridge-type: select <literal>communication</literal>
                or <literal>integration</literal>, depending on intended
                usage. For communication bridges, physical interfaces can be
                added to the bridge.</para>
              </listitem>
            </itemizedlist>
          </section>
        </section>
      </section>

      <section id="zero_touch_prov">
        <title>Zero Touch Provisioning</title>

        <para>Zero-Touch Provisioning (ZTP) refers to the process of when a
        device starts up for the first time and its initial configuration is
        pushed down by an external management system, so that it is setup for
        proper operation without additional manual intervention by an
        operator. ZTP is an alternative to Manual configuration.</para>

        <para>A variety of operations can occur as part of ZTP such as initial
        device setup, configuration of managed objects, etc. The goal is to
        set up a device to the maximum possible extent without forcing an
        operator to be physically present (initially) to manage the
        device.</para>

        <para>An offline configuration is usually prepared in advance for the
        uCPE Manager to setup the virtualization infrastructure on the uCPE
        device, as soon as a device enrolls into the management system.</para>

        <section id="offline_configuration">
          <title>Offline Configuration</title>

          <para>The Offline Configuration subsystem is used to pre-populate a
          configuration for a device that will be brought under management at
          a future point in time. When creating an offline configuration store
          a <literal>Device ID</literal> can be specified. This ID uniquely
          identifies the device to be initialized.</para>

          <para>Alternatively, a wildcard can be used in the <literal>Device
          ID</literal> field, which results in a configuration being pushed on
          all uCPE devices upon their initial connection towards the uCPE
          Manager.</para>

          <para>To create an offline configuration, from the top toolbar menu
          select <literal>Applications</literal> -&gt; <literal>Offline
          Config</literal> -&gt; <literal>Add</literal>. The following fields
          are available:</para>

          <itemizedlist>
            <listitem>
              <para>Name: name of the device.</para>
            </listitem>

            <listitem>
              <para>Device type: Enea universal CPE.</para>
            </listitem>

            <listitem>
              <para>Device version: 2.2.2</para>
            </listitem>

            <listitem>
              <para>Config Set: uCPE Config</para>
            </listitem>

            <listitem>
              <para>Device ID: device ID or a wildcard(*).</para>
            </listitem>

            <listitem>
              <para>Device Grouping Tags: a tag to group devices. These tags match 
                the customer tags provided during the installation of the device.</para>
            </listitem>
          </itemizedlist>

          <para>When a device connects to the uCPE Manager for the first time,
          it checks the device to see if it has been Zero Touch Provisioned
          (ZTP). If not, it looks for an offline configuration that matches
          these values, in the following order:</para>

          <itemizedlist>
            <listitem>
              <para>The Device ID.</para>
            </listitem>

            <listitem>
              <para>The set of tags.</para>
            </listitem>

            <listitem>
              <para>A "*" for Device ID (wildcard).</para>
            </listitem>
          </itemizedlist>

          <para>If a match is found, the offline configuration is sent to the
          device as part of Zero-Touch-Provisioning.</para>

          <para>After creating the Offline Config Store, access the device
          through <literal>Applications</literal> -&gt; <literal>offline
          config</literal> -&gt; <literal>Config App</literal> and provision
          it with the required initial configuration. This operation mirrors
          what happens during manual configuration described in the previous
          section.</para>
        </section>
      </section>

      <section id="custom_scripts">
        <title>Custom Scripts</title>

        <para>The custom scripts feature allows users to execute user-defined
        scripts on the uCPE device at various times.This allows for more
        flexible and advanced configurations such as a LTE modem
        configuration, advanced network configurations or OVS flow rule
        programming at any time.</para>

        <section id="upload_scripts">
          <title>Uploading Scripts</title>

          <para>The scripts need to be uploaded to the uCPE Manager prior to
          use. When uploading scripts to the uCPE Manager make sure to select
          the right script type.</para>

          <para>The following script types are supported:</para>

          <itemizedlist>
            <listitem>
              <para><literal>Once-before-startup</literal>. This script will
              only execute once during the startup.</para>
            </listitem>

            <listitem>
              <para><literal>Always-before-startup</literal>. This script will
              always execute during the startup.</para>
            </listitem>

            <listitem>
              <para><literal>Once-after-startup</literal>. This script will
              only execute once after the system has been started.</para>
            </listitem>

            <listitem>
              <para><literal>Always-after-startup</literal>. This script will
              always execute after the system has been started.</para>
            </listitem>
          </itemizedlist>

          <para>Follow the instruction below to upload scripts:</para>

          <orderedlist>
            <listitem>
              <para>Select <literal>Devices</literal> -&gt; <literal>Custom
              Scripts</literal> -&gt; <literal>Configure</literal>.</para>
            </listitem>

            <listitem>
              <para>Select <literal>Upload to EMS</literal>.</para>
            </listitem>

            <listitem>
              <para>In the <literal>Script Type</literal> menu, select the
              type the uploaded script should have.</para>
            </listitem>

            <listitem>
              <para>Press <literal>Choose File</literal> to select the scripts
              needed, and then press <literal>Send</literal>.</para>
            </listitem>
          </orderedlist>
        </section>

        <section id="remove_scripts">
          <title>Removing Scripts</title>

          <para>Follow the instruction below to remove scripts:</para>

          <orderedlist>
            <listitem>
              <para>Select <literal>Devices</literal> -&gt; <literal>Custom
              Scripts</literal> -&gt; <literal>Configure</literal>.</para>
            </listitem>

            <listitem>
              <para>Select the script you want to delete from the
              <literal>Uploaded Scripts</literal> tab and then click
              <literal>Delete</literal>, which will remove the script
              immediately from the uCPE Manager.</para>
            </listitem>
          </orderedlist>
        </section>

        <section id="configure_scripts">
          <title>Configuring Script Location</title>

          <para>The location where the scripts are staged in the uCPE Manager
          can be chanaged as described below:</para>

          <orderedlist>
            <listitem>
              <para>Select <literal>Devices</literal> -&gt; <literal>Custom
              Scripts</literal> -&gt; <literal>Configure</literal>.</para>
            </listitem>

            <listitem>
              <para>Select the <literal>Configuration</literal> tab and
              specify a new loacation to store the scripts.</para>

              <note>
                <para>Change the script storage location only if you have many
                scripts which you would prefer to store on another partition,
                otherwise leave this configuration as is.</para>
              </note>
            </listitem>
          </orderedlist>
        </section>

        <section id="run_the_scripts">
          <title>Running the Scripts</title>

          <para><emphasis role="bold">How to run Custom
          Scripts</emphasis></para>

          <orderedlist>
            <listitem>
              <para>Select <literal>Devices</literal> -&gt; <literal>Custom
              Scripts</literal> -&gt; <literal>Apply Scripts</literal>.</para>
            </listitem>

            <listitem>
              <para>In the <literal>Script Config Screen</literal> pop up,
              select the devices from the device(s) chooser list on which to
              run the scripts. Press the <literal>&gt;</literal> button to
              move the devices to the right side of the chooser, which is the
              list of devices that will execute the selected scripts.</para>
            </listitem>

            <listitem>
              <para>Select the scripts from the list under the device(s)
              chooser by pressing the <literal>+</literal> button.</para>
            </listitem>

            <listitem>
              <para>In the pop-up window, select the scripts from the list. If
              there are no scripts to select, then there is no script uploaded
              with that particular type. Upload the script(s) needed and try
              again.</para>
            </listitem>

            <listitem>
              <para>Check the checkbox <literal>Reboot devices</literal> if
              you want to reboot and execute the scripts at once and then
              press <literal>ok</literal>.</para>

              <note>
                <para>The status of execution for the scripts can be seen by
                opening the <literal>Fault</literal> -&gt;
                <literal>Events</literal> screen and filtering by device
                and/or the event name <filename>Custom</filename>.</para>
              </note>
            </listitem>
          </orderedlist>
        </section>
      </section>
    </section>
  </section>

  <section id="device_upgrade">
    <title>Device Upgrade</title>

    <section id="device_upgrade_process">
      <title>Device Upgrade Process</title>

      <para>Device Upgrade/Install performs the following operations to the
      device:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Prepare for upgrade</emphasis>. This
          stage tells the device that an upgrade is about to happen.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Install file on device</emphasis>. This
          stage copies the file to the uCPE device.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Upgrade Device</emphasis>. This stage
          causes the device to replace its running image with the newly copied
          image.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="managing_device_upgrade">
      <title>Managing the Device Upgrade</title>

      <para>Before an install or upgrade can be completed, certain
      configuration data must be set. Files also need to be uploaded to the
      Device Upgrade image repository in order to be uploaded to the
      device.</para>

      <para>Launch the Device Upgrade management console by selecting
      <literal>Devices</literal> -&gt; <literal>Upgrade</literal> from the top
      toolbar. The console when launched will contain the following
      tabs:</para>

      <itemizedlist>
        <listitem>
          <para><literal>Image Library</literal>. To add/delete an
          image.</para>
        </listitem>

        <listitem>
          <para><literal>Upgrade Operations</literal>. See running upgrades,
          cancel any upgrades in progress, start a device upgrade.</para>
        </listitem>

        <listitem>
          <para><literal>Configuration</literal>. Upgrade configuration
          parameters.</para>
        </listitem>
      </itemizedlist>

      <para>Press <literal>Close</literal> when the message <literal>File
      Uploaded Successfully</literal> appears on the File Upload
      Screen.</para>

      <section id="upload_image">
        <title>Image Library</title>

        <para><emphasis role="bold">Add an image to the image
        repository/library</emphasis></para>

        <orderedlist>
          <listitem>
            <para>Select <literal>Devices</literal> -&gt;
            <literal>Upgrade</literal>.</para>
          </listitem>

          <listitem>
            <para>Select <literal>Add</literal> from the <literal>Image
            Library</literal> tab to add a new image file.</para>
          </listitem>

          <listitem>
            <para>Click on <literal>Choose File</literal> to provide the path
            to the image file (must be of type
            <literal>rootfs.ostree.tar.bz2</literal>). Select the target
            hardware platform corresponding to the image being uploaded
            (xeon-d or atomc-3000).</para>
          </listitem>

          <listitem>
            <para>Click <literal>Send</literal> to upload the image to the
            image repository.</para>
          </listitem>
        </orderedlist>

        <para><emphasis role="bold">Delete an image from the image
        repository</emphasis></para>

        <orderedlist>
          <listitem>
            <para>Select <literal>Devices</literal> -&gt;
            <literal>Upgrade</literal>.</para>
          </listitem>

          <listitem>
            <para>Select the image you want to delete from the <literal>Image
            Library</literal> tab and then click
            <literal>Delete</literal>.</para>
          </listitem>
        </orderedlist>
      </section>

      <section id="multi_device_install">
        <title>Upgrade Operations</title>

        <para>The Upgrade Operations tab allows a user to manage device
        upgrades in the system. It allows the user to see all the upgrades
        that are currently in progress, as well as listing the completed ones.
        If an upgrade succeeds or fails, then a row will be added to the
        completed upgrades table. If one fails, the failure message will be
        visible here.</para>

        <note>
          <para>The list of completed upgrade tasks resides in memory and will
          not persist across reboots of the server.</para>
        </note>

        <para><emphasis role="bold">How to Install/Upgrade immediately or
        schedule for later</emphasis></para>

        <orderedlist>
          <listitem>
            <para>Select <literal>Devices</literal> -&gt;
            <literal>Upgrade</literal>.</para>
          </listitem>

          <listitem>
            <para>Select <literal>Upgrade Devices</literal> from the
            <literal>Upgrade Operations</literal> tab. This will launch a
            <literal>Multi Device Install Image</literal> screen that will
            allow the user to install and upgrade more than one device at a
            time or upgrade later.</para>

            <para>The configurable parameters are:</para>

            <itemizedlist>
              <listitem>
                <para><literal>Scheduling</literal>. Click this checkbox if
                the upgrade will be done later. Schedule the day, hour and
                minute for when to run the upgrade.</para>

                <note>
                  <para>The hour represents the local uCPE Manager server
                  hour.</para>
                </note>
              </listitem>

              <listitem>
                <para><literal>Description</literal>. An optional description
                of the operation. It is recommended to add a description so
                that different upgrades happening simultaneously can be
                distinguished.</para>
              </listitem>

              <listitem>
                <para><literal>Image File</literal>. Click on <literal>Choose
                Image File</literal> to select the image file.</para>
              </listitem>

              <listitem>
                <para><literal>Devices</literal>. The list of available
                devices is populated when an image file is chosen. The
                device(s) chooser is then populated with the list of devices
                that can accept that file. Press the <literal>&gt;</literal>
                button to move the devices to the right side of the chooser,
                which is the list of devices that will be upgraded.</para>
              </listitem>

              <listitem>
                <para><literal>Upgrade Operation</literal>. Available options
                are:</para>

                <itemizedlist>
                  <listitem>
                    <para><literal>Install and Activate</literal>. This will
                    do an image installation as well as an upgrade.</para>
                  </listitem>

                  <listitem>
                    <para><literal>Install Only</literal>. This will do an
                    image installation only. The image is copied to the
                    device, and an upgrade will be done later either at a
                    scheduled time or when the option <literal>Activate
                    Only</literal> is selected.</para>
                  </listitem>

                  <listitem>
                    <para><literal>Activate Only</literal>. This will activate
                    an already installed image on the device.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>
          </listitem>
        </orderedlist>
      </section>

      <section id="check_releases">
        <title>Releases installed on a Device</title>

        <para>The installed releases on a device can be viewed by selecting
        the device first, then from the top toolbar selecting
        <literal>Configuration</literal> -&gt; <literal>Upgrade</literal>. The
        installed releases on the device, the release status, release state,
        commit-id and release version will be listed in a table.</para>
      </section>

      <section id="check_device_status">
        <title>Device Status</title>

        <para>The status of the installation and upgrade can be viewed in the
        <literal>Upgrade Operations</literal> tab. Ongoing or scheduled
        upgrade operations can be viewed or cancelled.</para>

        <para><emphasis role="bold">To view the status of an installation or
        upgrade operations</emphasis></para>

        <orderedlist>
          <listitem>
            <para>Select <literal>Devices</literal> -&gt;
            <literal>Upgrade</literal>.</para>
          </listitem>

          <listitem>
            <para>Select <literal>Upgrade Operations</literal>. The ongoing
            operations are listed at the top and a history of failed or
            successful operations are listed at the bottom.</para>
          </listitem>

          <listitem>
            <para>Select an <emphasis>Active</emphasis> or <emphasis>Completed
            Upgrade Operation</emphasis> and click the <literal>Device
            Status</literal> button to see detailed information regarding the
            upgrade operation, including the devices involved and information
            per device.</para>
          </listitem>
        </orderedlist>

        <para><emphasis role="bold">To cancel an upgrade
        operation</emphasis></para>

        <orderedlist>
          <listitem>
            <para>Select <literal>Devices</literal> -&gt; <literal>Upgrade
            </literal> -&gt; <literal> Upgrade Operations</literal>.</para>
          </listitem>

          <listitem>
            <para>Select an operation from the list and press <literal>Cancel
            Upgrade</literal> and <literal>Confirm</literal>. The operation
            will then be deleted from the list.</para>
          </listitem>
        </orderedlist>
      </section>

      <section id="device_upgrade_config">
        <title>Configuration</title>

        <note>
          <para>The default values present in the configuration of each device
          are recommended for use. Modifying them is for an Advanced User
          only.</para>
        </note>

        <para><emphasis role="bold">How to Configure the uCPE device Upgrade
        </emphasis></para>

        <orderedlist>
          <listitem>
            <para>Select <literal>Devices</literal> -&gt;
            <literal>Upgrade</literal>.</para>
          </listitem>

          <listitem>
            <para>Select <literal>Configuration</literal>.</para>
          </listitem>

          <listitem>
            <para>The configurable parameters are:</para>

            <itemizedlist>
              <listitem>
                <para><literal>deviceImageDir</literal>. This is the disk
                location of the device image repository. If an absolute path
                name such as <literal>/usr/local/deviceimage</literal> is
                given, then the absolute path name is used. If no absolute
                pathname is given it is considered to be relative to the
                installation directory.</para>
              </listitem>

              <listitem>
                <para><literal>maxThreads</literal>. This number dictates how
                many upgrades the system can manage at one time, either
                individually launched or launched from the multi-device
                screens. This value defaults to 20, which means that 20
                devices may be updated at one time.</para>
              </listitem>

              <listitem>
                <para><literal>KeepAlive</literal>. This number represents the
                number of seconds that a thread will be kept alive before it
                is collected. If multiple installations are occurring, this
                will keep the thread alive for X seconds before it is
                released. If not released, it can be used by the internal
                scheduling system as soon as it has completed an
                upgrade.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </orderedlist>
      </section>

      <section id="related_func_devup">
        <title>Related Functionality for a Device Upgrade</title>

        <para>Each device can receive image files and use them to upgrade.
        This can be done by selecting the device in the
        <literal>System</literal> view and clicking the
        <literal>Upgrade</literal> button.</para>

        <para>In the new window, an upgrade image can be chosen from the
        <literal>Image Files</literal> tab by selecting the image file from
        the list and clicking the <literal>Install on Device</literal>
        button.</para>

        <para>Once an image is installed on the device, the image will be
        available on the device and be visible in the
        <literal>Releases</literal> tab. It can then be selected from the list
        and the upgrade started by clicking the <literal>Upgrade</literal>
        button.</para>
      </section>
    </section>
  </section>

  <section id="vnf_management">
    <title>VNF Management</title>

    <para>The Enea uCPE Manager is responsible for onboarding, configuring
    (e.g. CloudInit) and ensuring life cycle management of VNFs that are
    instantiated and run on the various uCPE devices.</para>

    <section id="onboarding_a_vnf">
      <title>Onboarding a VNF</title>

      <para>The onboarding of a VNF means adding it to the Enea uCPE Manager
      VNF Catalog and preparing it for instantiation (deployment on connected
      uCPE devices). This is accomplished using the Enea uCPE Manager
      Onboarding graphical user interface.</para>

      <para>Typically, the Getting Started Guide of a VNF contains all
      necessary information needed to onboard a VNF.</para>

      <section id="retrieve_art">
        <title>Retrieving Artifacts</title>

        <para>The user must first retrieve the necessary artifacts from the
        VNF vendor:</para>

        <orderedlist>
          <listitem>
            <para>Download the VNF from the commercial vendor.</para>
          </listitem>

          <listitem>
            <para>Procure any VNF-specific files from the VNF vendor, e.g.
            license file.</para>

            <note>
              <para>There are no standard ways of managing VNF licenses,
              therefore no general guidelines can be provided. One example of
              license handling that can be employed in the uCPE Manager is the
              adding of a license during the Cloud-Init setup.</para>
            </note>
          </listitem>

          <listitem>
            <para>Optionally, get access to the VNF specific VNF Manager for
            day 1 and 2 configuration (in cloud or for local
            deployment).</para>
          </listitem>

          <listitem>
            <para>Procure the Getting Started Guide from the VNF vendor,
            preferably for KVM deployment for VNF specific configuration
            information.</para>
          </listitem>
        </orderedlist>
      </section>

      <section id="onboard_prep">
        <title>Preparation</title>

        <para>Once all needed downloadables, documentation and more have been
        attained, preparation for onboarding must be completed:</para>

        <orderedlist>
          <listitem>
            <para>Determine the use-case and performance requirements of the
            VNF you wish to deploy:</para>

            <itemizedlist spacing="compact">
              <listitem>
                <para>This decides what resources the VNF is configured for,
                along with networking and day zero configurations.</para>

                <note>
                  <para>Generally, the Getting Started Guide for the VNF
                  provides guidelines for resource allocation, but since
                  performance is dependent on hardware capacity, the right
                  resource allocation for deployment is determined through
                  benchmarking.</para>
                </note>
              </listitem>

              <listitem>
                <para>Determine the amount of hardware resources needed for
                the VNF (RAM, number of CPUs and storage size).</para>
              </listitem>

              <listitem>
                <para>Determine how many Virtual Network Interfaces the VNF
                will use.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Determine the Day-0 configuration method from the VNF
            Getting Started guidelines.</para>

            <note>
              <para>For many VNFs, day zero configuration can be skipped in
              early onboarding efforts when automation is not of
              importance.</para>
            </note>
          </listitem>

          <listitem>
            <para>Determine any requirements needed by the Cloud-Init file
            structure and the content needed when this structure is
            used.</para>
          </listitem>
        </orderedlist>
      </section>

      <section id="onboard_in_ucpemg">
        <title>Onboarding into the uCPE Manager</title>

        <para><emphasis role="bold">How to onboard a VNF into the uCPE Manager
        </emphasis></para>

        <orderedlist>
          <listitem>
            <para>Select from the top toolbar <literal>VNF</literal> -&gt;
            <literal>Descriptors</literal></para>
          </listitem>

          <listitem>
            <para>Click the <literal>On-board</literal> button.</para>
          </listitem>

          <listitem>
            <para>When prompted by the UI, make sure the <literal>VM
            Image</literal> radio button at the top of the onboarding screen
            is selected, it will trigger a popup menu window.</para>
          </listitem>
        </orderedlist>

        <para>This window contains data fields where both necessary and
        optional information about the VNF can be supplied. After doing so,
        press the Onboard button, the uCPE Manager will create the VNF
        descriptor and add it to its VNF Catalog.</para>

        <figure>
          <title>Onboard a VNF</title>

          <mediaobject>
            <imageobject>
              <imagedata align="center" contentwidth="600"
                         fileref="images/onboard_a_vnf_image.png" />
            </imageobject>
          </mediaobject>
        </figure>

        <para><emphasis role="bold">Main fields</emphasis></para>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">VM Image File</emphasis>. This is the
            Virtual Machine image file for the VNF. Typically, it is a QCOW
            image. Press <literal>Choose File</literal> and select the image
            you wish to upload.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Image Format</emphasis>. Select the
            format which matches the image file format.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">VNF Type Name</emphasis>. This is the
            name that will be used to identify this VNF. It will be shown in
            the VNFs list.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Description</emphasis>. This field
            contains any description provided and is only displayed in the GUI
            tables in the uCPE Manager.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Version</emphasis>. This is the
            version of the current VNF that you are hosting. It's used to
            distinguish this VNF from other versions of the same type.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Memory in MB</emphasis>. This is the
            amount of memory (in megabytes) that will be provided to this type
            of VNF when it is instantiated. To determine the value for this
            field, consult the VNF vendor.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Num of CPUs</emphasis>. The number of
            CPUs that will be dedicated to an instance of this VNF when
            created. To determine the value for this field, consult the VNF
            vendor.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Storage in GB</emphasis>. How much
            disk space to provide an instance of this VNF. To determine the
            value for this field, consult the VNF vendor.</para>
          </listitem>
        </itemizedlist>

        <para><emphasis role="bold">Interfaces Tab</emphasis></para>

        <para>Click on the <literal>Interfaces</literal> tab to show the
        Interfaces table.</para>

        <para>This table will contain the interfaces required by this VNF to
        be configured, when creating an instance. Consult the VNF vendor to
        determine which and how many are required. Each interface requires a
        name, and optionally a description, used only by the uCPE
        Manager.</para>

        <note>
          <para>CAUTION: The user MUST conserve the same order for the virtual
          interfaces during both onboarding and instantiation phases.</para>
        </note>

        <para><emphasis role="bold">Cloud Init Tab</emphasis></para>

        <para>Click the <literal>Clout Init</literal> tab to provide the
        Clout-Init configuration. There are three fields that need to be
        populated:</para>

        <orderedlist>
          <listitem>
            <para><emphasis role="bold">Cloud-Init
            Datasource</emphasis></para>

            <para>To onboard a VNF you must specify the <literal>Cloud-Init
            Datasource</literal> that the VNF uses. This information is
            procured from the VNF Vendor. Choose one of the following methods
            to specify the datasource:</para>

            <itemizedlist spacing="compact">
              <listitem>
                <para><emphasis role="bold">None</emphasis>. If there is no
                datasource.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">ConfigDrive</emphasis>. This
                method allows you to provide any number of content-data files
                containing Cloud-Init data.</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">NoCloud</emphasis>. This is a
                simpler method that uses only one cloud init file
                (User-Data).</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">ISO</emphasis>. Pre-cooked
                cloud-init image. This image must be created by the user
                according to VNF requirements.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Cloud-Init Disk Type</emphasis></para>

            <para>The <literal>Cloud-Init Disk Type</literal> field must be
            set to either <literal>Disk</literal>, or
            <literal>CD-ROM</literal>, depending on what the VNF requires. You
            can get this information from the VNF Vendor.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Content Files Table</emphasis></para>

            <para>The <literal>Content Files Table </literal>is ONLY used if
            you choose <literal>ConfigDrive</literal> as the Cloud-Init
            Datasource. For each content file added, you must provide a
            <literal>Path</literal>. When a user uses the uCPE Manager to
            create an instance for multiple VNFs, they will be prompted to
            provide a data file for each entry in this table. Each type of VNF
            will require different cloud-init files, e.g.: a license file. The
            data files will be added to the cloud-init image that the user
            provides at the instantiation of the VNF. If the cloud-init image
            is not provided, no Cloud-Init Data Source will be created for
            that VNF and there will be no warning.</para>
          </listitem>
        </orderedlist>

        <para>Consult with the VNF vendor to determine what is required for
        the VNF you are onboarding.</para>

        <para><emphasis role="bold">Properties Tab</emphasis></para>

        <para>In this table, you can enter values for properties that will be
        used during instantiation of the VNF. The values will augment the
        default values in the <filename>Domain.XML</filename> file used by
        <literal>libvirt/virsh</literal> (running in NFV Access) when creating
        an instance of the VNF. Consult with the VNF Vendor or ENEA support
        for values needed by specific VNFs.</para>

        <para><emphasis role="bold">Property Values</emphasis></para>

        <itemizedlist>
          <listitem>
            <para><literal>numHugePages</literal> defines the number of huge
            memory pages the VNF uses (for DPDK).</para>
          </listitem>

          <listitem>
            <para><literal>vnfMgmtIpAddress</literal>: the IP address of the
            VNF's management interface, connected to a
            <literal>vnfMgmt</literal> bridge (e.g. 10.0.0.2).</para>
          </listitem>

          <listitem>
            <para><literal>internalMgmtPort</literal>: the VNF's TCP/UDP port
            used for management (e.g. 443).</para>
          </listitem>

          <listitem>
            <para><literal>externalMgmtPort</literal>: the Management port
            used for external access (e.g. 60001).</para>
          </listitem>
        </itemizedlist>

        <note>
          <para>The last three properties are useful in conjuction with the
          <literal>vnfMgmt</literal> bridge type. They allow the user to map
          the internal VNF management port to an external port, useful for VNF
          configuration from WAN.</para>

          <para>In the previous example, the internal TCP port 443 (HTTPS) was
          mapped to the external port 60001, which allows the user to access
          the VNF management port from a web browser e.g.
          <literal>https://&lt;WAN_IP&gt;:60001</literal>.</para>
        </note>
      </section>
    </section>

    <section id="instantiating_a_vnf">
      <title>Instantiating a VNF</title>

      <para>When a VNF is onboarded and available in the VNF catalog, it can
      be instantiated on connected uCPE devices. The configurations provided
      when the VNF is onboarded, serve as a template for instantiation. Before
      instantiating any VNF, please make sure the available storage space on
      the uCPE device is big enough to accommodate the VNF you need to
      instantiate.</para>

      <para>Follow the instructions below to instantiate a VNF:</para>

      <orderedlist>
        <listitem>
          <para>Select from the top toolbar <literal>VNF</literal> -&gt;
          <literal>Instances</literal></para>
        </listitem>

        <listitem>
          <para>Click the <literal>Add</literal> button.</para>
        </listitem>

        <listitem>
          <para>Fill out the following mandatory fields:</para>

          <itemizedlist spacing="compact">
            <listitem>
              <para>Name: a descriptive name.</para>
            </listitem>

            <listitem>
              <para>VNF Type: a list of onboarded VNFs.</para>
            </listitem>

            <listitem>
              <para>uCPE Device: the uCPE device to instantiate the VNF
              on.</para>
            </listitem>

            <listitem>
              <para>Networking Configuration:</para>

              <itemizedlist spacing="compact">
                <listitem>
                  <para>Connect each configured NIC with a bridge, SR-IOV or
                  PCI Passthrough.</para>
                </listitem>

                <listitem>
                  <para>Set up each NIC with a driver method.</para>
                </listitem>
              </itemizedlist>

              <note>
                <para>All configured NICs must be set up before instantiating
                a VNF. Failure to do so will end in a failed
                instantiation.</para>
              </note>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Add VNF-specific configuration data by uploading a Cloud-Init
          file (when the Cloud-Init is used).</para>
        </listitem>

        <listitem>
          <para>Add any VNF-specific files (e.g license files).</para>
        </listitem>

        <listitem>
          <para>Hit the <literal>Create</literal> button to deploy the VNF and
          run it on the specified uCPE device.</para>
        </listitem>
      </orderedlist>

      <para>Selecting the<literal> VNF -&gt; Events</literal> menu will show
      that the VNF was created and a connection was established.</para>
    </section>

    <section id="enter_console">
      <title>Accessing the VNF console</title>

      <para>Once the VNF is deployed, the VNF console can be entered using SSH
      and virsh commands. The VNF Console is a typical starting point for
      determining a successful deployment and configuring a VNF beyond Day
      Zero.</para>

      <orderedlist>
        <listitem>
          <para>SSH to the uCPE device from the Enea uCPE Manager
          (<literal>Device-&gt;SSH</literal>) using user:
          <literal>root</literal> and no password.</para>
        </listitem>

        <listitem>
          <para>In SSH:</para>

          <orderedlist spacing="compact">
            <listitem>
              <para>Use the <command>virsh list</command> command to list all
              running VNFs and to determine the VNF's instance number.</para>
            </listitem>

            <listitem>
              <para>Use the <command>virsh console &lt;instance
              number&gt;</command> command to enter the VNF-specific
              console.</para>
            </listitem>
          </orderedlist>
        </listitem>
      </orderedlist>
    </section>
  </section>
</chapter>