GettingStarted: add Custom Scripts chapter

Change-Id: I8dd3fbf29fac4003782e153128a3cff345424869
Signed-off-by: Sona Sarmadi <sona.sarmadi@enea.com>

1 files changed, 212 insertions, 47 deletions

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 3155be6..095d2d5 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
@@ -885,6 +885,160 @@
           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>
 
@@ -910,8 +1064,8 @@
 
         <listitem>
           <para><emphasis role="bold">Upgrade Device</emphasis>. This stage
-          causes the device to replace its running image with the newly
-          copied image.</para>
+          causes the device to replace its running image with the newly copied
+          image.</para>
         </listitem>
       </itemizedlist>
     </section>
@@ -919,9 +1073,9 @@
     <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>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
@@ -930,7 +1084,8 @@
 
       <itemizedlist>
         <listitem>
-          <para><literal>Image Library</literal>. To add/delete an image.</para>
+          <para><literal>Image Library</literal>. To add/delete an
+          image.</para>
         </listitem>
 
         <listitem>
@@ -948,10 +1103,9 @@
           parameters.</para>
         </listitem>
       </itemizedlist>
-      
-          <para>Press "Close" when the message <literal>File Uploaded
-          Successfully</literal> appears on the File Upload Screen.</para>
 
+      <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>
@@ -1005,14 +1159,18 @@
 
         <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>
+        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>
+        <para><emphasis role="bold">How to Install/Upgrade immediately or
+        schedule for later</emphasis></para>
 
         <orderedlist>
           <listitem>
@@ -1021,19 +1179,19 @@
           </listitem>
 
           <listitem>
-            <para>Select <literal>Upgrade Devices</literal> from the 
-              <literal>Upgrade Operations</literal> tab. This will launch a
+            <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>
-            
+            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>
+                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
@@ -1043,8 +1201,8 @@
 
               <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
+                of the operation. It is recommended to add a description so
+                that different upgrades happening simultaneously can be
                 distinguished.</para>
               </listitem>
 
@@ -1055,15 +1213,16 @@
 
               <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>
+                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>
+                <para><literal>Upgrade Operation</literal>. Available options
+                are:</para>
 
                 <itemizedlist>
                   <listitem>
@@ -1073,9 +1232,10 @@
 
                   <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>
+                    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>
@@ -1106,8 +1266,8 @@
         <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>
+        <para><emphasis role="bold">To view the status of an installation or
+        upgrade operations</emphasis></para>
 
         <orderedlist>
           <listitem>
@@ -1142,15 +1302,19 @@
       <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>
+        <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>
+            <para>Select <literal>Devices</literal> -&gt;
+            <literal>Upgrade</literal>.</para>
           </listitem>
 
           <listitem>
@@ -1164,10 +1328,10 @@ recommended for use. Modifying them is for an Advanced User only.</para></note>
               <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>
+                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>
@@ -1181,10 +1345,11 @@ recommended for use. Modifying them is for an Advanced User only.</para></note>
               <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>
+                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>