path: root/doc/book-enea-edge-getting-started/doc/upgrade_ena.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="upgrade_ena">
  <title>Upgrading Enea Edge</title>

  <para>Enea provides regular releases that will require the upgrading of Enea
 Edge components. The Enea Edge Management application must be upgraded
  first, followed by upgrading the Enea Edge Runtime on the uCPE
  devices.</para>

  <section id="upgrade_mg">
    <title>Upgrading the Enea Edge Management application</title>

    <note>
      <para>It is recommended to create a system backup by accessing the
      <emphasis role="bold">System</emphasis> menu and selecting <emphasis
      role="bold">System Backup</emphasis> from the Enea Edge Management GUI,
      for recovery in case of an upgrade failure.</para>
    </note>

    <orderedlist>
      <listitem>
        <para>Extract the
        <filename>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
        folder.</para>

        <para>The directory in which the archive has been unpacked will be
        denoted as <literal>&lt;EEMg-installerdir&gt;</literal>.</para>
      </listitem>

      <listitem>
        <para>Enter <literal>&lt;EEMg-installerdir&gt;/dist</literal>.</para>
      </listitem>

      <listitem>
        <para>Run the following command with the root account and change
        <literal>/opt/ems</literal> to the correct location of the Enea Edge
        Management installation:</para>

        <programlisting>./upgrade.sh /opt/ems \
Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
      </listitem>
    </orderedlist>

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

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

      <listitem>
        <para>Create a compressed file of the <literal>ucpemanager</literal>
        application folder
        (<filename>EneaEdgeManagement-Backup-YYYYddMMHHmm.tar.gz</filename>), which
        contains a snapshot of the existing installation in the
        <literal>&lt;EEMg-installerdir&gt;/dist</literal> directory.</para>

        <note>
          <para>The snapshot file created during the upgrade can be used for
          restoring the Enea Edge Management application.</para>
        </note>
      </listitem>

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

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

    <para><olink targetdoc="book_enea_edge_getting_started"
    targetptr="fresh_ucpemg_install">Fresh Installation of the Enea Edge
    Management in the <ns:include
    href="../../s_docbuild/olinkdb/pardoc-names.xml"
    xmlns:ns="http://www.w3.org/2001/XInclude"
    xpointer="element(book_enea_edge_getting_started/1)" /></olink> Manual
    contains information about the input required to be entered during the
    execution of the upgrade script.</para>

    <para condition="hidden">For an example on how to upgrade an Enea Edge
    Management installation in a High Availability setup, consult <olink
    targetdoc="book_enea_edge_getting_started"
    targetptr="ha_upgrade">Upgrading a High Availability Deployment in the
    <ns:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
    xmlns:ns="http://www.w3.org/2001/XInclude"
    xpointer="element(book_enea_edge_getting_started/1)" /></olink>
    Manual.</para>

    <section id="restore_prev_ucpe_install">
      <title>Restoring a previous Enea Edge Management Installation</title>

      <para><emphasis role="bold">How to restore a previous Enea Edge
      Management installation</emphasis></para>

      <orderedlist>
        <listitem>
          <para>Extract
          <filename>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename></para>
        </listitem>

        <listitem>
          <para>The directory in which the archive has been unpacked will be
          denoted as <literal>&lt;EEMg-installerdir&gt;</literal>.</para>
        </listitem>

        <listitem>
          <para>Copy the snapshot file
          (<filename>EneaEdgeManagement-Backup-YYYYddMMHHmm.tar.gz</filename>)
          created during a previous Enea Edge Management Upgrade or Enea Edge
          Management Uninstall Operation into the
          <literal>&lt;EEMg-installerdir&gt;/dist</literal> directory.</para>
        </listitem>

        <listitem>
          <para>Enter <literal>&lt;EEMg-installerdir&gt;/dist</literal>.</para>
        </listitem>

        <listitem>
          <para>Run the following command with the root user and change
          <literal>/opt/ems</literal> to the correct location of the Enea Edge
          Management installation:</para>

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

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

      <itemizedlist>
        <listitem>
          <para>Remove any vestiges of the existing
          <literal>ucpemanager</literal> service, if they exist.</para>
        </listitem>

        <listitem>
          <para>Reinstall the Enea Edge Management application on the
          specified target location, restoring the data in the database and
          files in the process.</para>
        </listitem>
      </itemizedlist>

      <para>The <literal>ucpemanager</literal> service will then start with
      the older version now running on the system.</para>
    </section>

    <section id="uninstall_ucpem_install">
      <title>Uninstalling an existing Enea Edge Management
      Installation</title>

      <para><emphasis role="bold">How to uninstall an existing Enea Edge
      Management installation</emphasis></para>

      <orderedlist>
        <listitem>
          <para>Navigate to the folder where the Enea Edge Management
          application is unpacked:
          <filename>&lt;EEMg-installerdir&gt;</filename>.</para>
        </listitem>
        
        <listitem>
          <para>Enter
          <literal>&lt;EEMg-installerdir&gt;/dist</literal>.</para>
        </listitem>

        <listitem>
          <para>Run the following command with the root user and change
          <literal>/opt/ems</literal> to the correct location of the Enea Edge
          Management installation:</para>

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

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

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

        <listitem>
          <para>Create a compressed file of the <literal>ucpemanager</literal>
          application folder:
          <filename>EneaEdgeManagement-Backup-YYYYddMMHHmm.tar.gz</filename>, which
          contains a snapshot of the existing installation and functions as a
          restore point.</para>

          <note>
            <para>The snapshot file created during the uninstall can be used
            for restoring the Enea Edge Management application.</para>
          </note>
        </listitem>

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

        <listitem>
          <para>Uninstall the database service.</para>
        </listitem>

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

      <para>After these steps, the Enea Edge Management application is
      completely removed from the system.</para>
    </section>
  </section>

  <section id="upgrade_devices">
    <title>uCPE device Upgrades</title>

    <para>A uCPE device can be upgraded using the Enea Edge Management
    GUI.</para>

    <section id="device_up_process">
      <title>The uCPE device Upgrade Process</title>

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

      <orderedlist>
        <listitem>
          <para><emphasis role="bold">Prepare for upgrade.</emphasis> This
          stage prepares the files needed for an upgrade.</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
          upgrades the uCPE device to a newer version.</para>
        </listitem>
      </orderedlist>

      <note>
        <para>Upgrading from Enea NFV Access 2.3.0 is not possible when using
        the Enea Edge Management application in HTTPS mode. Either switch to
        HTTP by accessing the <emphasis role="bold">System</emphasis> menu,
        clicking on <emphasis role="bold">Configuration</emphasis>, then
        <emphasis role="bold">Web Access</emphasis> and checking the <emphasis
        role="bold">Enable HTTP</emphasis> box, or by installing Edge Enea
        2.4.0 on the device manually.</para>
      </note>
    </section>

    <section id="mg_upgrade">
      <title>Managing the uCPE device Upgrade</title>

      <para>Before an installation 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
      <emphasis role="bold">Devices</emphasis> and then the <emphasis
      role="bold">Upgrade</emphasis> button from the top tool-bar. The console
      will contain the following tabs:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Image Library</emphasis>. To add/delete
          an image.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Upgrade Operations</emphasis>. See
          upgrades that are currently running, cancel any upgrades in
          progress, or start a uCPE device upgrade.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Configuration</emphasis>. Upgrade
          configuration parameters.</para>
        </listitem>
      </itemizedlist>

      <note>
        <para>The uCPE Device upgrade is done with image files of the type
        <literal>ostree.tar.bz2</literal>, which are available in the
        <filename>Enea_Edge_Runtime_&lt;processor&gt;_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
        file you downloaded with your release.</para>
      </note>

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

        <para><emphasis role="bold">Adding an image to the image
        repository/library</emphasis><orderedlist>
            <listitem>
              <para>Select <emphasis role="bold">Devices</emphasis> and then
              the <emphasis role="bold">Upgrade</emphasis> button.</para>
            </listitem>

            <listitem>
              <para>Select <emphasis role="bold">Add</emphasis> from the
              <emphasis role="bold">Image Library</emphasis> tab to add a new
              image file.</para>
            </listitem>

            <listitem>
              <para>Select <emphasis role="bold">Choose File</emphasis> to
              provide the path to the image file (must be of type
              <literal>ostree.tar.bz2</literal>).</para>
            </listitem>

            <listitem>
              <para>Select the target hardware platform corresponding to the
              image being uploaded (<literal>xeon-d</literal> or
              <literal>atom-c3000</literal>).</para>
            </listitem>

            <listitem>
              <para>Click <emphasis role="bold">Send</emphasis> to upload the
              image to the image repository.</para>
            </listitem>
          </orderedlist></para>

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

        <orderedlist>
          <listitem>
            <para>Select <emphasis role="bold">Devices</emphasis> and then the
            <emphasis role="bold">Upgrade</emphasis> button.</para>
          </listitem>

          <listitem>
            <para>Select the image you want to delete from the <emphasis
            role="bold">Image Library</emphasis> tab and then click <emphasis
            role="bold">Delete</emphasis>.</para>
          </listitem>
        </orderedlist>
      </section>

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

        <para>The <emphasis role="bold">Upgrade Operations</emphasis> tab
        allows a user to manage uCPE 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 in the table.</para>

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

        <para><emphasis role="bold">How to Install/Upgrade a device
        immediately or schedule the process for later</emphasis><orderedlist>
            <listitem>
              <para>Select <emphasis role="bold">Devices</emphasis> and then
              the <emphasis role="bold">Upgrade</emphasis> button.</para>
            </listitem>

            <listitem>
              <para>Select <emphasis role="bold">Upgrade Devices</emphasis>
              from the <emphasis role="bold">Upgrade Operations</emphasis>
              tab. This will launch a <literal>Multi Device Install
              Image</literal> screen that will allow the user to install and
              upgrade more than one uCPE device at a time or upgrade
              later.</para>
            </listitem>
          </orderedlist></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 Enea Edge Management
              application 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 <emphasis
            role="bold">Choose Image File</emphasis> to select the image
            file.</para>
          </listitem>

          <listitem>
            <para><literal>Devices</literal>. The list of uCPE Devices that
            can accept an image file is populated when the image file is
            chosen.</para>

            <para>Mark the uCPE devices that you wish to upgrade and press the
            <emphasis role="bold">&gt;</emphasis> button to move the uCPE
            devices to the right side of the selector. Those chosen form the
            list of uCPE devices that will be upgraded.</para>
          </listitem>

          <listitem>
            <para><literal>Upgrade Operation</literal>. The 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 uCPE 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 uCPE device.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>To start the upgrade, click <emphasis
            role="bold">ok</emphasis>.</para>
          </listitem>
        </itemizedlist>

        <note>
          <para>When the uCPE device activates the upgrade, it will be
          rebooted automatically.</para>
        </note>
      </section>

      <section id="releases_installed">
        <title>Releases installed on a uCPE device</title>

        <para>The installed releases on a uCPE device can be viewed by
        selecting the uCPE device first, then from the top toolbar selecting
        <emphasis role="bold">Configuration</emphasis> and then the <emphasis
        role="bold">Upgrade</emphasis> button.</para>

        <para>The installed releases on the uCPE device, the release status,
        release state, <literal>commit-id</literal> and release version will
        be listed in a table.</para>
      </section>

      <section id="upgrade_status">
        <title>uCPE device Upgrade Status</title>

        <para>The status of the installation and upgrade can be viewed in the
        <emphasis role="bold">Upgrade Operations</emphasis> tab. Ongoing or
        scheduled upgrade operations can be viewed or canceled.</para>

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

        <orderedlist>
          <listitem>
            <para>Select <emphasis role="bold">Devices</emphasis> and then the
            <emphasis role="bold">Upgrade</emphasis> button.</para>
          </listitem>

          <listitem>
            <para>Select <emphasis role="bold">Upgrade Operations</emphasis>.
            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 role="bold">Active</emphasis> or
            <emphasis role="bold">Completed Upgrade Operation</emphasis> and
            then the <emphasis role="bold">Device Status</emphasis> button to
            see detailed information regarding the upgrade operation,
            including the uCPE devices involved and information per uCPE
            device.</para>
          </listitem>
        </orderedlist>

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

        <orderedlist>
          <listitem>
            <para>Select <emphasis role="bold">Devices</emphasis>, then the
            <emphasis role="bold">Upgrade</emphasis> button and choose
            <emphasis role="bold">Upgrade Operations</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Select an operation from the list and choose <emphasis
            role="bold">Cancel Upgrade</emphasis> and <emphasis
            role="bold">Confirm</emphasis>. The operation will then be deleted
            from the list.</para>
          </listitem>
        </orderedlist>
      </section>

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

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

        <para><emphasis role="bold">How to Configure the uCPE device
        Upgrade</emphasis><orderedlist>
            <listitem>
              <para>Select <emphasis role="bold">Devices</emphasis> and then
              the <emphasis role="bold">Upgrade</emphasis> button.</para>
            </listitem>

            <listitem>
              <para>Select <emphasis
              role="bold">Configuration</emphasis>.</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.</para>

                  <note>
                    <para>If no absolute path name is given it is assumed to
                    be relative to the installation directory.</para>
                  </note>
                </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 uCPE
                  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></para>
      </section>

      <section id="related_functionality">
        <title>Related Functionality for a uCPE device Upgrade</title>

        <para>Each uCPE device can receive image files and use them to
        upgrade. This can be done by selecting the uCPE device in the
        <emphasis role="bold">System</emphasis> view and clicking the
        <emphasis role="bold">Upgrade</emphasis> button. In the new window, an
        upgrade image can be chosen from the <emphasis role="bold">Image
        Files</emphasis> tab by selecting the image file from the list and
        clicking the <emphasis role="bold">Install on Device</emphasis>
        button. The Image files that appear in the <emphasis role="bold">Image
        Library</emphasis> tab can be uploaded to the Enea Edge Management
        Application by following the steps listed in <link
        linkend="image_lib">Image Library</link>.</para>

        <para>Once an image is installed on the uCPE device, the image will be
        available on the uCPE device and be visible in the <emphasis
        role="bold">Releases</emphasis> tab. There are two ways to make it
        active, choose one or the other:</para>

        <itemizedlist>
          <listitem>
            <para>Select it from the list and then start the upgrade by
            clicking the <emphasis role="bold">Upgrade</emphasis>
            button.</para>
          </listitem>

          <listitem>
            <para>Select <emphasis role="bold">Operations</emphasis>, then 
            <emphasis role="bold">Upgrade</emphasis>, enter the
            <literal>Release Name</literal> and press <emphasis
            role="bold">Execute</emphasis>. Filling in the <literal>Restore
            Archive</literal> text field is optional and should be left unset
            if the <literal>NFVi Snapshot</literal> feature is
            disabled.</para>
          </listitem>
        </itemizedlist>

        <para>If an installed image is no longer needed, it can be removed
        from the device by selecting <emphasis
        role="bold">Operations</emphasis> and <emphasis role="bold">Remove
        Release</emphasis>. In the <emphasis role="bold">Remove
        Release</emphasis> window, provide the <literal>Release Name</literal>
        and press <emphasis role="bold">Execute</emphasis>.</para>
      </section>
    </section>
  </section>
</chapter>