Merge "GettingStarted: add device upgrade chapter" into rocko

2 files changed, 313 insertions, 9 deletions

diff --git a/doc/book-enea-nfv-access-getting-started/doc/eltf_params_updated.xml b/doc/book-enea-nfv-access-getting-started/doc/eltf_params_updated.xml
index 7fe09ec..be0be23 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/eltf_params_updated.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/eltf_params_updated.xml
@@ -42,7 +42,7 @@ export PATH=~/bin:$PATH</programlisting></para>
     correct also compared to the "previous" REL VER in pardoc-distro.xml
     "prev_baseline".</bridgehead>
 
-    <para id="EneaLinux_REL_VER"><phrase>2.2.1</phrase></para>
+    <para id="EneaLinux_REL_VER"><phrase>2.2.2</phrase></para>
 
     <para id="Yocto_VER"><phrase>2.4</phrase></para>
 
diff --git a/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml b/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml
index 688c278..3155be6 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml
@@ -178,8 +178,8 @@
 
       <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>
 
@@ -195,7 +195,7 @@
 
       <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>
+      <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>
@@ -380,7 +380,7 @@
       <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>
+      and files in the process.</para>
 
       <para>The ucpemanager service is then started and the older version is
       now running on the system.</para>
@@ -888,6 +888,311 @@
     </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 to upload 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>Device Status</literal>. Shows the device
+          status.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>Configuration</literal>. Upgrade configuration
+          parameters.</para>
+        </listitem>
+      </itemizedlist>
+      
+          <para>Press "Close" 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. 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 time zone is set to Eastern Standard Time
+                  (EST).</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>Device Status</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>Device Status</literal>. The ongoing
+            operations are listed at the top and a history of failed or
+            successful operations are listed at the bottom.</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 now 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>
+  </section>
+
   <section id="vnf_management">
     <title>VNF Management</title>
 
@@ -1163,8 +1468,8 @@
             <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.
-            </para>
+            will require different cloud-init files, e.g.: a license
+            file.</para>
           </listitem>
         </orderedlist>
 
@@ -1209,7 +1514,7 @@
           <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>
+          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
@@ -1224,8 +1529,7 @@
 
       <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.
-      </para>
+      when the VNF is onboarded, serve as a template for instantiation.</para>
 
       <para>Follow the instructions below to instantiate a VNF:</para>