Merge "GettingStarted: add call home to ZTP section"

4 files changed, 161 insertions, 13 deletions

diff --git a/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml b/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml
index 4062dd3..a954df5 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/device_configuration_and_provisioning.xml
@@ -266,16 +266,19 @@
   <section id="zero_touch_prov">
     <title>Zero Touch Provisioning</title>
 
-    <para>Zero-Touch Provisioning is an alternative to Manual configuration.
-    ZTP is a feature that allows the device to be provisioned and configured
-    automatically, with minimal manual work involved when adding devices to a
-    network. Demonstrated when a device boots for the first time, 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.</para>
+    <para>Zero-Touch Provisioning (ZTP) is an alternative to Manual
+    configuration. ZTP refers to the process by which, when a device starts up
+    for the first time, 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.</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>In order to create a static configuration supporting ZTP, the uCPE
-    Manager user needs to identify the device ID of the machine running NFV
+    Manager user needs to identify the <literal>Device ID</literal> of the machine running NFV
     Access.</para>
 
     <para>During the automatic installation process when the
@@ -283,8 +286,9 @@
     menu <literal>Customize kernel parameters</literal> and set the
     <literal>uCPE Manager IP</literal> address. Please check <xref
     linkend="install_ena_stick" />, step 7 for how to set the uCPE Manager IP
-    address at boot time.</para>
-
+    address at boot time. The Device ID will be listed in the installer under
+    the <literal>Customize kernel parameters</literal> menu.</para>
+     
     <para>With the address parameter set, run
     <literal>list_deviceID.sh</literal> after NFV Access is installed and
     booted, to get the device ID of the target.</para>
@@ -302,8 +306,152 @@
     <para>An offline configuration can be prepared in advance for the uCPE
     Manager to setup the infrastructure on the device.</para>
 
-    <para>For more details about ZTP, please see the <literal>Zero Touch
-    Provisioning Guide </literal>from the <literal>DeveloperDocs</literal>
-    archive provided with your release.</para>
+    <section id="adding_a_device">
+      <title>Adding a Device</title>
+
+      <para>The uCPE Manager must be configured to bring the target device under
+      management. This is done by using the <literal>Devices -&gt; Manage
+      -&gt; Add</literal> menu:</para>
+
+      <figure>
+        <title>Adding a Device</title>
+
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/add_a_device.png"
+                       scale="50" />
+          </imageobject>
+        </mediaobject>
+      </figure>
+
+      <para>The relevant parameters on this screen are described below:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Type. The type of device to be added, i.e <literal>Enea universal uCPE
+          </literal>.</para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
+          <para>Name. The name by which the device is referred to in the uCPE Manager.</para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
+          <para>IP Address. IP address of the device. If a device is installed under a
+          local/private network and not directly visible to the uCPE Manager machine, the
+          Gateway IP of the private network must be used.</para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
+          <para>SSH Port. The NETCONF Port used for communications. This is a relevant
+          parameter if the standard NETCONF SSH (i.e. not Call-Home) is being used. Default
+          is set to 22.</para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
+          <para>SSH User Name. The user name for SSH connectivity. Default user is
+           <literal>root</literal>.</para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
+          <para>SSH Password/Private Key/Passphrase. The Authentication Credentials, use
+          one of the aforementioned as appropriate. Default password is empty.</para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
+          <para>Device Calls Home. This checkbox indicates the direction of device
+           communications. When cleared, the uCPE Manager will initiate a connection to
+           the device. When checked, the device will initiate a connection by opening a
+           socket to the uCPE Manager for NETCONF traffic (over SSH), while the uCPE
+           Manager waits for device connection.</para>
+        </listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <listitem>
+          <para>Device ID. The unique instance ID of the device. This is what links a
+          device to its day-0 configuration (stored in the offline configuration system).
+          It is a required field if you want to perform Zero-Touch Provisioning.</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section id="offline_configuration">
+      <title>Offline Configuration</title>
+
+      <para>The Offline Configuration subsystem (which is designed as a uCPE
+      Manager Application Module) 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, an optional<literal>
+      Device ID</literal> can be specified - this ID uniquely identifies the
+      device to be initialized.</para>
+
+      <para>Use the GUI (shown below) launched by the <literal>Applications
+      -&gt; Offline Config -&gt; Add</literal> menu:</para>
+
+      <figure>
+        <title>Onboard New VNF</title>
+
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/offline_config.png"
+                       scale="80" />
+          </imageobject>
+        </mediaobject>
+      </figure>
+
+      <para>Specify the exact value of the <literal>Device ID</literal> in the
+      required field. This will tag the device needed for the initial configuration
+      provided by the offline configuration store. Choose <literal>Merge</literal> as
+      the Default Upload Method if you do not want any boot configuration set on the
+      device, to be wiped out. Selecting <literal>Replace</literal> will set the
+      entire device configuration to match values in the offline configuration.</para>
+
+      <para>After creating the Offline Config Store, access the device through <literal>
+      Applications -> offline config -> Config App</literal> and provision it with the
+      required initial configuration. This operation mirrors what happens during regular
+      offline configuration.</para>
+
+      <para>Now that the store has been provisioned successfully, it is ready to send
+      this configuration to the device when it first comes online.</para>
+    </section>
+
+    <section id="initial_communications">
+      <title>Initial Communications</title>
+
+      <para>There are two possible paths to this process, depending upon
+      whether or not NETCONF Call-Home functionality is used:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>If Call-Home is not enabled/supported, the uCPE Manager creates a SSH
+          session to the device over the port configured through the <literal>Add Device
+          </literal> process (default 830). It then initiates NETCONF communications over
+          this session.</para>
+        </listitem>
+
+        <listitem>
+          <para>If the device uses Call-Home, it creates a socket connection to port 4334
+          on the management system which runs the uCPE Manager. The uCPE Manager then
+          creates a SSH session over this socket and initiates NETCONF communications as
+          a client.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>Once communications with the device have been established, the
+      Device Manager will try and connect to it.</para>
+    </section>
   </section>
 </chapter>
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/add_a_device.png b/doc/book-enea-nfv-access-getting-started/doc/images/add_a_device.png
new file mode 100755
index 0000000..cb240b6
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/add_a_device.png
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/customized_parameters.png b/doc/book-enea-nfv-access-getting-started/doc/images/customized_parameters.png
new file mode 100755
index 0000000..cf36244
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/customized_parameters.png
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/offline_config.png b/doc/book-enea-nfv-access-getting-started/doc/images/offline_config.png
new file mode 100755
index 0000000..280d004
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/offline_config.png