summaryrefslogtreecommitdiffstats
path: root/doc/book-enea-edge-getting-started
diff options
context:
space:
mode:
Diffstat (limited to 'doc/book-enea-edge-getting-started')
-rw-r--r--doc/book-enea-edge-getting-started/doc/advanced_configurations.xml1166
-rw-r--r--doc/book-enea-edge-getting-started/doc/book.xml44
-rw-r--r--doc/book-enea-edge-getting-started/doc/grafana.xml361
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/archive_list.pngbin0 -> 87667 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/collect_debug_logs.pngbin0 -> 47994 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/debug_settings.pngbin0 -> 32833 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/dev_file_mg.pngbin0 -> 138952 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/download_files.pngbin0 -> 79979 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/edit_inter.pngbin0 -> 9000 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/edit_inter_config.pngbin0 -> 37721 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/fault_events.pngbin0 -> 46986 bytes
-rw-r--r--doc/book-enea-edge-getting-started/doc/images/high_av_setup.pngbin0 -> 66687 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/onboard_a_vnf_image.pngbin0 -> 19864 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/ovs_bridges_tab.pngbin0 -> 55326 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/prep_deploy.pngbin0 -> 127794 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/prep_execution.pngbin0 -> 121264 bytes
-rw-r--r--doc/book-enea-edge-getting-started/doc/images/telemetry_settings.pngbin0 -> 28977 bytes
-rw-r--r--doc/book-enea-edge-getting-started/doc/images/telemetry_start.pngbin0 -> 14763 bytes
-rwxr-xr-xdoc/book-enea-edge-getting-started/doc/images/vnf_space.pngbin0 -> 39641 bytes
-rw-r--r--doc/book-enea-edge-getting-started/doc/images/wap_external_interface.pngbin0 -> 18534 bytes
-rw-r--r--doc/book-enea-edge-getting-started/doc/images/wap_wireless_ap.pngbin0 -> 21250 bytes
-rw-r--r--doc/book-enea-edge-getting-started/doc/installation_guide.xml1255
-rw-r--r--doc/book-enea-edge-getting-started/doc/introduction.xml269
-rw-r--r--doc/book-enea-edge-getting-started/doc/log_collector.xml418
-rw-r--r--doc/book-enea-edge-getting-started/doc/net_config_options.xml913
-rw-r--r--doc/book-enea-edge-getting-started/doc/troubleshooting.xml228
-rw-r--r--doc/book-enea-edge-getting-started/doc/upgrade_ena.xml623
-rw-r--r--doc/book-enea-edge-getting-started/doc/vnf_mg.xml529
-rwxr-xr-xdoc/book-enea-edge-getting-started/swcomp.mk10
29 files changed, 5816 insertions, 0 deletions
diff --git a/doc/book-enea-edge-getting-started/doc/advanced_configurations.xml b/doc/book-enea-edge-getting-started/doc/advanced_configurations.xml
new file mode 100644
index 0000000..c596735
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/advanced_configurations.xml
@@ -0,0 +1,1166 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="advanced_conf">
5 <title>Advanced Configurations</title>
6
7 <para>This chapter describes possible configurations for advanced features
8 such as the Hugepage Reservation Service customization, UEFI Secure Boot and
9 Bare Metal Provisioning.</para>
10
11 <section id="bare_meta_prov">
12 <title>Bare Metal Provisioning</title>
13
14 <para>Bare Metal Provisioning can be used for automated deployment of the
15 Enea Edge Runtime on a large number of uCPE devices. The uCPE devices may
16 have no previous operating system installed, or are reinstalled without
17 preserving any existing data. Enea Edge Bare Metal Provisioning is based
18 on standardized Pre-Boot Execution environment (PXE) booting.</para>
19
20 <para>The Bare Metal Provisioning process begins by PXE booting an Enea
21 Edge installer <literal>initramfs</literal> image. The installer downloads
22 a configuration file, as well as the Enea Edge Runtime image and then
23 proceeds to install the system by dividing the disk into 2 partitions: a
24 GPT partition containing the GRUB boot loader and a second partition
25 containing the Enea Edge Runtime root filesystem. When the installation is
26 complete, the uCPE device is automatically rebooted into the Enea Edge
27 Runtime.</para>
28
29 <note>
30 <para>The <literal>.hddimg</literal>, <literal>initramfs</literal>, and
31 <literal>bzImage</literal> files are available in the
32 <filename>Enea_Edge_Runtime_&lt;processor&gt;_&lt;version&gt;-&lt;build_number&gt;.tar.gz</filename>
33 file downloaded with your release.</para>
34 </note>
35
36 <section id="bare_meta_prov_prereq">
37 <title>Prerequisites</title>
38
39 <itemizedlist>
40 <listitem>
41 <para>The uCPE devices to be installed are connected in a working
42 PXE network boot environment. The PXE server can be set up using any
43 Linux distribution that includes TFTP and DHCP software packages.
44 Refer to the documentation for your distribution for setup
45 instructions.</para>
46 </listitem>
47
48 <listitem>
49 <para>An HTTP server must be available and accessible from the uCPE
50 devices in the provisioning network. Note that the installer will
51 use the same interface that the uCPE device is PXE-booted from, to
52 obtain an IP address using DHCP and access the HTTP server.</para>
53 </listitem>
54
55 <listitem>
56 <para>The uCPE devices are preconfigured in BIOS to boot from the
57 hard drive where the Enea Edge Runtime will be installed.</para>
58 </listitem>
59
60 <listitem>
61 <para>CSM support and Dual Boot must be enabled in BIOS (i.e. PXE
62 booting in legacy mode), while the final Enea Edge Runtime image
63 will boot in UEFI mode. Doing a mass deployment using legacy PXE
64 booting usually means that Secure Boot is disabled, Secure Boot will
65 need to be enabled afterwards.</para>
66 </listitem>
67
68 <listitem>
69 <para>A remote management tool such as <literal>ipmitool</literal>
70 (or a vendor-specific tool) is available for use to set the next
71 boot option to PXE and reboot the uCPE devices in order to begin the
72 installation.</para>
73 </listitem>
74 </itemizedlist>
75 </section>
76
77 <section id="bare_meta_prov_server">
78 <title>Server Configuration</title>
79
80 <para>The following images provided with your Enea Edge release need to
81 be made available on the PXE and HTTP servers:</para>
82
83 <orderedlist>
84 <listitem>
85 <para>Copy the Enea Edge installer <literal>initramfs</literal>
86 image and kernel <literal>bzImage</literal> for your uCPE device
87 architecture to the TFTP directory on the PXE server (e.g
88 <literal>/var/lib/tftpboot</literal>).</para>
89 </listitem>
90
91 <listitem>
92 <para>Compress the Enea Edge Runtime <literal>.hddimg</literal>
93 image for the uCPE device architecture using <literal>gzip</literal>
94 and copy the resulting <literal>hddimg.gz</literal> file to the HTTP
95 server.</para>
96 </listitem>
97 </orderedlist>
98
99 <section id="bare_meta_prov_install_config">
100 <title>Installation Configuration File</title>
101
102 <para>An installation configuration file needs to be prepared on the
103 HTTP server. The format of the configuration file is a list of
104 "<literal>name = value</literal>" pairs and the available parameters
105 are described below:</para>
106
107 <itemizedlist>
108 <listitem>
109 <para><literal>image_url</literal> (mandatory). The HTTP server
110 URL used for downloading the Enea Edge Runtime image.</para>
111 </listitem>
112
113 <listitem>
114 <para><literal>install_drive</literal> (optional). The name of the
115 drive where the Enea Edge Runtime will be installed (e.g
116 <literal>/dev/sda</literal>). If not set, the installer will use
117 the largest detected (non-USB) drive on the uCPE device.</para>
118 </listitem>
119
120 <listitem>
121 <para><literal>prompt_user</literal> (optional). If the parameter
122 is set to "yes", the installer will ask for confirmation before
123 formatting and partitioning the drive. The default behaviour is to
124 proceed automatically without any user interaction.</para>
125 </listitem>
126 </itemizedlist>
127
128 <para>Installation Configuration File Example:</para>
129
130 <programlisting>image_url = http://192.168.1.100/enea-nfv-access-xeon-d.hddimg.gz
131install_drive = /dev/sda</programlisting>
132
133 <note>
134 <para>The installation configuration file needs to use the Linux
135 end-of-line format (\n), not the Windows format (\r\n).</para>
136 </note>
137 </section>
138
139 <section id="bare_meta_prov_pxe">
140 <title>PXE Configuration</title>
141
142 <para>A PXE entry for the Enea Edge installation needs to be added as
143 the default boot selection in the pxelinux configuration file (e.g
144 <literal>/var/lib/tftpboot/pxelinux.cfg/default</literal>). The PXE
145 entry should have the following settings:</para>
146
147 <programlisting>default nfv_access
148label nfv_access
149menu label ^NFV_ACCESS_INSTALLER
150kernel &lt;Path to kernel&gt;
151append root=/dev/ram0 initrd=&lt;Path to initramfs&gt; LABEL=pxe-installer \
152 INSTALL_CFG=http://&lt;Server IP&gt;/&lt;Path to install config file&gt; \
153 console=ttyS0,115200 earlyprintk=ttyS0,115200
154ipappend 2</programlisting>
155 </section>
156 </section>
157
158 <section id="bare_meta_prov_inst">
159 <title>Starting the Installation</title>
160
161 <para>To initiate the installation, set the boot device (for next boot
162 only) to PXE and reboot the uCPE devices. How to do this depends on the
163 remote management capabilities of the uCPE devices and may require
164 vendor-specific tools.</para>
165
166 <para>Example initiation using <literal>ipmitool</literal>:</para>
167
168 <programlisting>ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; chassis bootdev pxe
169ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; power reset </programlisting>
170
171 <para>The uCPE devices should be configured in BIOS to boot from the
172 installation drive first in order to automatically start Enea Edge
173 Runtime when the installation is finished.</para>
174 </section>
175 </section>
176
177 <section id="uefi_secure_boot">
178 <title>UEFI Secure Boot</title>
179
180 <para>Secure Boot was designed to enhance security in the pre-boot
181 environment. It prevents malicious software and applications from being
182 loaded during the system start-up process.</para>
183
184 <para>The basic principle of UEFI Secure Boot is that it requires all
185 artifacts involved in the boot process (bootloaders, kernel, initramfs) to
186 be signed using a set of private keys. On a Secure Boot enabled uCPE
187 device these artifacts are checked against a set of public certificates
188 which correspond to these keys. If there are any mismatches the boot
189 process will fail at the stage(s) they are detected.</para>
190
191 <para>For more information about Secure Boot please refer to <ulink
192 url="https://www.uefi.org/sites/default/files/resources/UEFI_Secure_Boot_in_Modern_Computer_Security_Solutions_2013.pdf">Secure
193 Boot in Modern Computer Security Solutions</ulink>.</para>
194
195 <section id="secure_boot_keys">
196 <title>Enabling UEFI Secure Boot</title>
197
198 <para>All Enea Edge image artifacts delivered with the release are
199 signed using the Enea UEFI Secure boot private keys. These artifacts can
200 be used on a uCPE device that doesn't have Secure Boot enabled. To use
201 the Secure Boot feature, however, the user must make the Enea UEFI
202 Secure Boot public certificates available on the uCPE device before
203 enabling the feature in BIOS. This process is called
204 "Provisioning".</para>
205
206 <section id="manual_key_provisioning">
207 <title>Provisioning the Enea UEFI Secure Boot Certificates</title>
208
209 <para>The UEFI firmware is normally shipped with factory preloaded
210 certificates. If these do not already include Certificates from Enea,
211 they will need to be appended or replaced with the Enea
212 Certificates.</para>
213
214 <para><emphasis role="bold">UEFI Secure Boot certificates provided
215 with your release:</emphasis></para>
216
217 <itemizedlist>
218 <listitem>
219 <para><literal>Platform Key (PK)</literal>: this key protects the
220 next key from uncontrolled modification. Once this key is
221 enrolled, Secure Boot enters into <literal>User Mode</literal>.
222 The drivers and loaders signed with the <literal>Platform
223 Key</literal> can then be loaded by the firmware.</para>
224 </listitem>
225
226 <listitem>
227 <para><literal>Key Exchange key (KEK)</literal>: this key allows
228 other certificates which have a connection to the private portion
229 of the <literal>Platform Key</literal> to be used.</para>
230 </listitem>
231
232 <listitem>
233 <para><literal>Authorized Signature (DB)</literal>: contains the
234 <literal>trusted keys</literal> used for authenticating any
235 drivers or applications executed in the UEFI environment.</para>
236 </listitem>
237 </itemizedlist>
238
239 <para>The Enea UEFI Secure Boot certificates are installed together
240 with the Enea Edge Runtime onto the hard drive. They can be found on
241 the EFI partition (usually the first partition of the drive) under
242 <literal>/uefi_sb_keys</literal>.</para>
243
244 <para>These certificates need to be manually enrolled in BIOS. The
245 exact details on how to proceed may vary depending the version of the
246 UEFI firmware.</para>
247
248 <para>The UEFI firmware is normally shipped with factory preloaded
249 certificates. If these do not already include Certificates from Enea,
250 they will need to be appended or replaced with the Enea
251 Certificates.</para>
252 </section>
253
254 <section id="enable_secure_boot">
255 <title>Enabling Secure Boot in BIOS</title>
256
257 <para>Once the certificates are enrolled, Secure Boot needs to be
258 enabled in BIOS and the device rebooted.</para>
259 </section>
260 </section>
261 </section>
262
263 <section id="hugepage_reservation">
264 <title>Hugepage Reservation Service</title>
265
266 <para>Huge page memory support is a mechanism that allows the Linux kernel
267 to support larger page sizes than the default page unit (4KB). Huge pages
268 are contiguous blocks of memory that come in 2MB or 1GB sizes. By using
269 huge page allocations, less memory is used for page tables and the
270 Translation Lookaside Buffer (TLB) miss rate is significantly reduced.
271 Enea Edge Runtime uses huge page backed memory in KVM guests in order to
272 improve performance.</para>
273
274 <para>Enea Edge Runtime implements an automatic hugepage allocation
275 service that is triggered at each startup. The service is skipped if
276 hugepages have been allocated in the kernel boot command line.</para>
277
278 <para>There are two strategies outlined for hugepage allocation:</para>
279
280 <itemizedlist>
281 <listitem>
282 <para>If a system has an amount of memory up to 8GB, the allocation
283 algorithm will reserve up to 30% (no more than 2GB), for the OS and
284 the rest as 2MB hugepages.</para>
285 </listitem>
286
287 <listitem>
288 <para>If a system has an amount of memory that's higher than 8GB, the
289 allocation algorithm will reserve all but 2GB of memory as 1GB
290 hugepages, leaving the rest (2GB) to be used by the OS.</para>
291 </listitem>
292 </itemizedlist>
293
294 <note>
295 <para>This is a best effort reservation after kernel boot, so the
296 results may vary accordingly.</para>
297 </note>
298
299 <section id="hugepage_customizing_auto">
300 <title>Customizing Automatic Hugepage Reservation</title>
301
302 <para>Configuration of Hugepage reservation is done in
303 <literal>/etc/enea-nfv-access/hugepages.cfg</literal>.</para>
304
305 <para><emphasis role="bold">Parameters used by the automatic algorithm:
306 </emphasis></para>
307
308 <itemizedlist spacing="compact">
309 <listitem>
310 <para><literal>hugepage_setup</literal>: Enables the automatic
311 configuration algorithm. It has only one value,
312 <literal>auto</literal>. For manual configuration comment or remove
313 this parameter. Use the other parameter descriptions as a
314 template/example.</para>
315 </listitem>
316
317 <listitem>
318 <para><literal>threshold_to_use_1g</literal>: Decides the threshold
319 which instructs the algorithm to use 1GB hugepages. If a system's
320 memory is higher than <literal>threshold_to_use_1g</literal>, then
321 the algorithm will use 1GB hugepages, otherwise it will use 2MB
322 hugepages.</para>
323 </listitem>
324
325 <listitem>
326 <para><literal>percent_os_alloc</literal>: Decides how much memory
327 to try to reserve for userspace applications. The algorithm will try
328 to reserve at least the value of <literal>percent_os_alloc</literal>
329 of the total system memory for userspace applications.</para>
330 </listitem>
331
332 <listitem>
333 <para><literal>maximum_os_alloc_mb</literal>: Maximum amount of
334 memory to allocate for userspace applications. If
335 <literal>percent_os_alloc</literal> of the total system memory
336 exceeds <literal>maximum_os_alloc_mb</literal> then the maximum
337 allocated memory for userspace applications is
338 <literal>maximum_os_alloc_mb</literal>.</para>
339 </listitem>
340 </itemizedlist>
341
342 <para><emphasis role="bold">Example of automatic Hugepage
343 Configuration:</emphasis></para>
344
345 <programlisting>hugepage_setup = auto
346threshold_to_use_1g = 8192
347percent_os_alloc = 30
348maximum_os_alloc_mb = 2048</programlisting>
349
350 <para>The following possible allocations can result (based on total
351 system memory available):</para>
352
353 <itemizedlist>
354 <listitem>
355 <para>2GB of memory: approximately 30% will be allocated for the OS
356 and the rest will be allocated as 2MB hugepages.</para>
357 </listitem>
358
359 <listitem>
360 <para>4GB of memory: approximately 30% will be allocated for the OS
361 and the rest will be allocated as 2MB hugepages.</para>
362 </listitem>
363
364 <listitem>
365 <para>16GB of memory: approximately 2GB will be allocated for the OS
366 and the rest as 1GB hugepages.</para>
367 </listitem>
368 </itemizedlist>
369
370 <note>
371 <para>The memory allocated for the kernel and hugepages might vary
372 slightly depending on how much memory is available.</para>
373 </note>
374 </section>
375
376 <section id="hugepage_customizing_man">
377 <title>Customizing Manual Hugepage Reservation</title>
378
379 <para>The automatic algorithm can be disabled and hugepages in turn,
380 configured manually. To do this, comment the line which defines
381 <literal>hugepage_setup</literal> as <literal>auto</literal> and
382 configure memory for each CPU socket in the following manner:</para>
383
384 <programlisting>&lt;NUMA node&gt;.&lt;hugepage size&gt; = &lt;number of pages&gt;</programlisting>
385
386 <para>Where <literal>&lt;NUMA node&gt;</literal> refers to a node which
387 is part of the system's NUMA topology, <literal>&lt;hugepage
388 size&gt;</literal> decides what type of hugepages should be set and
389 <literal>&lt;number of hugepages&gt;</literal> is how many hugepages of
390 <literal>&lt;hugepage size&gt;</literal> should be allocated.</para>
391
392 <para>To list the available system nodes, run:</para>
393
394 <programlisting>ls -d /sys/devices/system/node/node* </programlisting>
395
396 <para>To list available hugepage sizes, per node, run:</para>
397
398 <programlisting>ls -d /sys/devices/system/node/node*/hugepages/hugepages-*</programlisting>
399
400 <para>Example of Manual Hugepage Configuration, configuring the system
401 to allocate three 1GB hugepages and 512 of 2MB hugepages on node:</para>
402
403 <programlisting>node0.2048kB = 512
404node0.1048576kB = 3 </programlisting>
405
406 <note>
407 <para>Make sure there are no hugepages reserved in the kernel boot
408 command line, these will override any manual configuration done in the
409 service.</para>
410 </note>
411 </section>
412 </section>
413
414 <section id="create_certificate">
415 <title>Tomcat Certificate Generation</title>
416
417 <para>The self-signed Tomcat Certificate the Enea Edge
418 Management application uses is generated at installation time. It can
419 be regenerated anytime after installation by using the
420 <filename>createCertificate.sh</filename> script.</para>
421
422 <para>On the CentOS 7 server open a terminal, log into a bash shell with
423 the root account and perform the following:</para>
424
425 <orderedlist>
426 <listitem>
427 <para>Extract <literal>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</literal></para>
428
429 <para>The directory in which the archive has been unpacked will be
430 denoted as: <literal>&lt;uCPEM-installerdir&gt;</literal>.</para>
431 </listitem>
432
433 <listitem>
434 <para>Enter <literal>&lt;uCPEM-installerdir&gt;/dist</literal>.</para>
435 </listitem>
436
437 <listitem>
438 <para>Run the following command:</para>
439
440 <programlisting>./createCertificate.sh ucpemanager &lt;IP_or_domain&gt; \
441 /opt/ems [&lt;service_username&gt;]</programlisting>
442
443 <para>Where the following need to be included:</para>
444
445 <itemizedlist>
446 <listitem>
447 <para>The IP or domain name of the server the Enea Edge
448 Management application is running on.</para>
449 </listitem>
450
451 <listitem>
452 <para>The service username, which is the one set when installing the
453 Enea Edge Management application. For more details
454 see <olink targetdoc="book_enea_edge_getting_started"
455 targetptr="fresh_ucpemg_install">Fresh Installation of the Enea
456 Edge Management application in the <ns:include
457 href="../../s_docbuild/olinkdb/pardoc-names.xml"
458 xmlns:ns="http://www.w3.org/2001/XInclude"
459 xpointer="element(book_enea_edge_getting_started/1)" /></olink> Manual.
460 Providing the service username is optional. If it is not provided, the default
461 value will be used.</para>
462 </listitem>
463 </itemizedlist>
464 </listitem>
465
466 <listitem>
467 <para>Restart the Enea Edge Management service:</para>
468
469 <programlisting>service ucpemanager restart</programlisting>
470 </listitem>
471 </orderedlist>
472 </section>
473
474 <section condition="hidden" id="high_availability_ig">
475 <title>Installing the Enea Edge Management application in High
476 Availability Mode</title>
477
478 <para>The following describes the setup needed for running the Enea Edge
479 Management application in High Availabilty (HA) mode, with a MariaDB
480 database cluster. A setup example is illustrated in the diagram
481 below.</para>
482
483 <figure>
484 <title>The High Availability setup</title>
485
486 <mediaobject>
487 <imageobject>
488 <imagedata align="center" contentwidth="600"
489 fileref="images/high_av_setup.png" />
490 </imageobject>
491 </mediaobject>
492 </figure>
493
494 <para>The setup consists of two sub-clusters, placed in different
495 geographical locations, each consisting of three MariaDB servers. In this
496 example, two of the machines are running only MariaDB, while the rest are
497 hosting a MariaDB server and an Enea Edge Management instance. The entire
498 network is hidden behind a firewall that performs NAT. While in protection
499 (cluster) mode, the Enea Edge Management application instances promote a
500 single Virtual IP (VIP). The cluster can be reached either from the
501 primary server IP or via VIP (recommended), since the VIP interface is
502 spawned on the primary server. In case of a primary failure, a newly
503 elected primary (from one of the backups) will respawn the VIP interface.
504 The firewall in this scenario will allocate a public IP for the outside
505 world that will be translated into the VIP. Also in this example, the
506 traffic towards the cluster from outside the firewall is done through
507 HTTPS, which will be translated to HTTP inside the private network.</para>
508
509 <note>
510 <para>By default, communication to the Enea Edge Management application
511 is done with HTTPS. To enable HTTP, go to <emphasis
512 role="bold">System</emphasis>, <emphasis
513 role="bold">Configuration</emphasis>, click on the <emphasis
514 role="bold">Web Access</emphasis> tab and check the <emphasis
515 role="bold">Enable HTTP</emphasis> checkbox.</para>
516 </note>
517
518 <para><emphasis role="bold">High-Availability - Design
519 Limitations</emphasis></para>
520
521 <para>Enea's solution for Edge Management High-Availability is designed to
522 maximize resiliency of the management function. However, the current design
523 does not provide guaranteed consistency across all Enea Edge
524 Management instances, i.e. some information might become out-of-sync in
525 certain conditions.</para>
526
527 <para>In order to reach full consistency, design would rely on
528 transactional data updates across the Primary instance and all Backups,
529 but the latency would significantly increase for all management
530 operations, which is considered to be a severe limitation.</para>
531
532 <para>In the current version of the Enea Edge Management application when
533 in High Availability mode, there are two kinds of data that needs to be
534 synchronized: data in the database and data residing in the Primary
535 instance filesystem. This means that there are intervals when data is
536 being synchronized from the Primary instance to the Backup(s) and Primary
537 failure at this time will result in incomplete/inconsistent data on the
538 Backup(s). For example, a VNF which has been onboarded on the Primary
539 instance will not be visible in a Backup instance(s) until both database
540 and filesystem have been synchronized. If a Backup instance becomes the
541 active one before synchronization takes place, this would result in an
542 out-of-sync state.</para>
543
544 <section id="ha_reqs">
545 <title>Requirements for High Availability</title>
546
547 <para>The following hardware is needed for deploying the base
548 configuration:</para>
549
550 <itemizedlist>
551 <listitem>
552 <para>Machines running the Enea Edge Management application and
553 MariaDB:</para>
554
555 <itemizedlist spacing="compact">
556 <listitem>
557 <para>4 CPU cores</para>
558 </listitem>
559
560 <listitem>
561 <para>12 - 16 GB memory</para>
562 </listitem>
563
564 <listitem>
565 <para>256 - 512 GB hard disk</para>
566 </listitem>
567 </itemizedlist>
568 </listitem>
569
570 <listitem>
571 <para>Machines running only MariaDB:</para>
572
573 <itemizedlist spacing="compact">
574 <listitem>
575 <para>2 CPU cores</para>
576 </listitem>
577
578 <listitem>
579 <para>8 GB memory</para>
580 </listitem>
581
582 <listitem>
583 <para>256 - 512 GB hard disk</para>
584 </listitem>
585 </itemizedlist>
586 </listitem>
587 </itemizedlist>
588 </section>
589
590 <section id="firewall_rules">
591 <title>Firewall Rules</title>
592
593 <para>Please refer to <olink targetdoc="book_enea_edge_getting_started"
594 targetptr="firewall_config">Firewall Configuration in the <xi:include
595 href="../../s_docbuild/olinkdb/pardoc-names.xml"
596 xmlns:xi="http://www.w3.org/2001/XInclude"
597 xpointer="element(book_enea_edge_getting_started/1)" /></olink> Manual.
598 In addition, the following configuration is needed:</para>
599
600 <orderedlist>
601 <listitem>
602 <para>Disable <literal>SELINUX</literal> on all database servers by
603 editing <literal>/etc/sysconfig/selinux</literal> and changing the
604 following:</para>
605
606 <programlisting>SELINUX=disabled
607SELINUXTYPE=targeted</programlisting>
608 </listitem>
609
610 <listitem>
611 <para>Reboot the server:</para>
612
613 <programlisting>[root@localhost ~]# sudo shutdown -r now</programlisting>
614 </listitem>
615 </orderedlist>
616
617 <para>The following ports should be opened in the local firewall (not
618 the one doing NAT), for each Enea Edge Management machine:</para>
619
620 <table>
621 <title>Ports for Enea Edge Management Machines</title>
622
623 <tgroup cols="2">
624 <colspec align="left" />
625
626 <thead>
627 <row>
628 <entry align="center">Port (Protocol)</entry>
629
630 <entry align="center">Usage</entry>
631 </row>
632 </thead>
633
634 <tbody>
635 <row>
636 <entry>80 (TCP)</entry>
637
638 <entry>HTTP</entry>
639 </row>
640
641 <row>
642 <entry>443 (TCP)</entry>
643
644 <entry>HTTPS</entry>
645 </row>
646
647 <row>
648 <entry>54327 (UDP)</entry>
649
650 <entry>Cluster multicasting (Hazelcast)</entry>
651 </row>
652
653 <row>
654 <entry>5701 - 5708 (TCP)</entry>
655
656 <entry>Hazelcast communications</entry>
657 </row>
658
659 <row>
660 <entry>4334 (TCP)</entry>
661
662 <entry>NETCONF call-home</entry>
663 </row>
664
665 <row>
666 <entry>7000 - 7009 (TCP)</entry>
667
668 <entry>Reverse SSH connection pool</entry>
669 </row>
670 </tbody>
671 </tgroup>
672 </table>
673
674 <para>For MariaDB, the following ports must be opened (on each MariaDB
675 server, including the ones hosting the Enea Edge Management
676 application):</para>
677
678 <table>
679 <title>Ports for MariaDB Machines</title>
680
681 <tgroup cols="2">
682 <colspec align="left" />
683
684 <thead>
685 <row>
686 <entry align="center">Port (Protocol)</entry>
687
688 <entry align="center">Usage</entry>
689 </row>
690 </thead>
691
692 <tbody>
693 <row>
694 <entry>3306 (TCP)</entry>
695
696 <entry>Client connections</entry>
697 </row>
698
699 <row>
700 <entry>4567 (UDP/TCP)</entry>
701
702 <entry>Galera cluster replication with multicasting</entry>
703 </row>
704
705 <row>
706 <entry>4568 (TCP)</entry>
707
708 <entry>Incremental state transfer</entry>
709 </row>
710
711 <row>
712 <entry>4444 (TCP)</entry>
713
714 <entry>State snapshot transfer</entry>
715 </row>
716 </tbody>
717 </tgroup>
718 </table>
719
720 <para>The following ports should be accessible externally and translated
721 to the Virtual IP side as shown below:</para>
722
723 <table>
724 <title>Ports for Virtual IP</title>
725
726 <tgroup cols="3">
727 <colspec align="left" />
728
729 <thead>
730 <row>
731 <entry align="center">External Port (Protocol)</entry>
732
733 <entry align="center">Usage</entry>
734
735 <entry align="center">Local Port (Protocol)</entry>
736 </row>
737 </thead>
738
739 <tbody>
740 <row>
741 <entry>443 (TCP)</entry>
742
743 <entry>HTTPS to/back HTTP</entry>
744
745 <entry>80 (TCP)</entry>
746 </row>
747
748 <row>
749 <entry>4334 (TCP)</entry>
750
751 <entry>NETCONF call-home</entry>
752
753 <entry>4334 (TCP)</entry>
754 </row>
755
756 <row>
757 <entry>7000 - 7009 (TCP)</entry>
758
759 <entry>Reverse SSH connection pool</entry>
760
761 <entry>7000 - 7009 (TCP)</entry>
762 </row>
763 </tbody>
764 </tgroup>
765 </table>
766 </section>
767
768 <section id="ha_installation">
769 <title>Installing High Availability</title>
770
771 <para>The Enea Edge Management application can be installed in High
772 Availability mode with a MariaDB database cluster by performing the
773 following steps. The mandatory Java configuration is also
774 detailed.</para>
775
776 <section id="ha_mariadb">
777 <title>Installing and configuring the MariaDB cluster</title>
778
779 <para>Install the latest MariaDB packages on all servers.</para>
780
781 <note>
782 <para>The setup was tested using MariaDB 10.5.8, built for CentOS
783 7.</para>
784 </note>
785
786 <para><emphasis role="bold">How to install MariaDB</emphasis></para>
787
788 <orderedlist>
789 <listitem>
790 <para>Install the MariaDB official yum repository. Create a file
791 named <literal>mariadb.repo</literal> in
792 <literal>/etc/yum.repos.d/</literal> with the following
793 content:</para>
794
795 <programlisting># MariaDB 10.5 CentOS repository list - created 2021-02-16 08:46 UTC
796# http://downloads.mariadb.org/mariadb/repositories/
797[mariadb]
798name = MariaDB
799baseurl = http://yum.mariadb.org/10.5/centos7-amd64
800gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
801gpgcheck=1
802</programlisting>
803
804 <note>
805 <para>For more information about setting the repository, consult
806 <ulink
807 url="https://downloads.mariadb.org/mariadb/repositories/#mirror=nxtHost">Downloads
808 - Setting up MariaDB Repositories</ulink>.</para>
809 </note>
810 </listitem>
811
812 <listitem>
813 <para>Make sure the following packages are installed:</para>
814
815 <programlisting>MariaDB-compat-10.5.8-1.el7.centos.x86_64
816MariaDB-common-10.5.8-1.el7.centos.x86_64
817MariaDB-server-10.5.8-1.el7.centos.x86_64
818MariaDB-client-10.5.8-1.el7.centos.x86_64
819galera-4-26.4.6-1.el7.centos.x86_64</programlisting>
820
821 <para>These provide the MariaDB server, client and the Galera
822 <literal>wsrep</literal> provider library.</para>
823 </listitem>
824
825 <listitem>
826 <para>Copy the <literal>wsrep</literal> template:</para>
827
828 <programlisting>[root@localhost ~]# cp /usr/share/mysql/wsrep.cnf /etc/my.cnf.d
829 </programlisting>
830 </listitem>
831
832 <listitem>
833 <para>Change the following configuration in
834 <filename>/etc/my.cnf.d/wsrep.cnf</filename>:</para>
835
836 <programlisting># Full path to wsrep provider library or 'none'
837<emphasis role="bold">wsrep_provider=/usr/lib64/galera-4/libgalera_smm.so</emphasis>
838
839# Provider specific configuration options
840#wsrep_provider_options=
841
842# Logical cluster name. Should be the same for all nodes.
843<emphasis role="bold">wsrep_cluster_name="ucpemanager"</emphasis>
844
845# Group communication system handle
846<emphasis role="bold">wsrep_cluster_address="gcomm://192.168.10.11,192.168.10.12,..,192.168.10.16"</emphasis>
847
848# Human-readable node name (non-unique). Hostname by default.
849<emphasis role="bold">wsrep_node_name=Node1</emphasis> # current node's name. set node name for each server in \
850the cluster
851
852# Base replication &lt;address|hostname&gt;[:port] of the node.
853# The values supplied will be used as defaults for state transfer receiving,
854# listening ports and so on. Default: address of the first network interface.\
855<emphasis role="bold">wsrep_node_address=192.168.10.11</emphasis>
856#current node's interface IP . must be set for each node in the cluster</programlisting>
857
858 <note>
859 <para>Steps 2, 3 and 4 must be performed for each MariaDB node
860 in the cluster.</para>
861 </note>
862 </listitem>
863
864 <listitem>
865 <para>Bootstrap the first node in the cluster (referred to as
866 <literal>Node1</literal> in this example), by running:</para>
867
868 <programlisting>[root@localhost ~]# galera_new_cluster</programlisting>
869
870 <para>This script passes the
871 <literal>--wsrep-new-cluster</literal> to
872 <literal>mysqld</literal> which tells the node that there is no
873 pre-existing cluster to connect to. The node will create a new
874 UUID to identify the new cluster.</para>
875
876 <note>
877 <para>Do not execute this script when connecting to an existing
878 cluster. It will create a new UUID to identify the cluster
879 again, and the node won't reconnect to the old cluster.</para>
880 </note>
881 </listitem>
882
883 <listitem>
884 <para>Go to <literal>Node1</literal> and start the service:</para>
885
886 <programlisting>[root@localhost ~]# systemctl start mariadb</programlisting>
887
888 <para>Subsequently, start the service on the other servers.</para>
889 </listitem>
890
891 <listitem>
892 <para>Verify that the nodes have entered the cluster:</para>
893
894 <programlisting>[root@localhost ~]# mysql --host=localhost --user=root -p
895MariaDB [(none)]&gt; show status like 'wsrep_cluster_conf_%';
896+-----------------------+-------+
897| Variable_name | Value |
898+-----------------------+-------+
899| wsrep_cluster_conf_id | 3 |
900+-----------------------+-------+
9011 row in set (0.001 sec)</programlisting>
902 </listitem>
903
904 <listitem>
905 <para>Run the initial configuration script (only once, on one of
906 the machines in the cluster):</para>
907
908 <programlisting>[root@localhost ~]# mysql_secure_installation
909
910Switch to unix_socket authentication [Y/n] <emphasis role="bold">Y</emphasis>
911Enabled successfully!
912Reloading privilege tables..
913 ... Success!
914…
915Change the root password? [Y/n] <emphasis role="bold">Y</emphasis>
916New password:
917Re-enter new password:
918Password updated successfully!
919Reloading privilege tables..
920 ... Success!
921…
922Remove anonymous users? [Y/n] <emphasis role="bold">Y</emphasis>
923 ... Success!
924…
925Disallow root login remotely? [Y/n] <emphasis role="bold">Y</emphasis>
926 ... Success!
927…
928Remove test database and access to it? [Y/n] <emphasis role="bold">Y (optional)</emphasis>
929 - Dropping test database...
930 ... Success!
931 - Removing privileges on test database...
932 ... Success!
933Reload privilege tables now? [Y/n] <emphasis role="bold">Y</emphasis>
934 ... Success!
935
936Cleaning up...
937
938All done! If you've completed all of the above steps, your MariaDB
939installation should now be secure.
940
941Thanks for using MariaDB!</programlisting>
942 </listitem>
943
944 <listitem>
945 <para>Create the initial database and grant access to it:</para>
946
947 <programlisting>[root@localhost application]# mysql --host=localhost --user=root -p
948MariaDB [(none)]&gt; CREATE DATABASE ucpemanager CHARACTER SET='utf8' \
949COLLATE='utf8_bin';
950Query OK, 1 row affected (0.004 sec)
951
952MariaDB [(none)]&gt; GRANT ALL PRIVILEGES ON ucpemanager.* \
953TO 'enea'@'%' IDENTIFIED BY 'somepassword' WITH GRANT OPTION;</programlisting>
954 </listitem>
955 </orderedlist>
956 </section>
957
958 <section id="ha_java_sdk_install">
959 <title>Installing the Java SDK</title>
960
961 <para>Please refer to <olink
962 targetdoc="book_enea_edge_getting_started"
963 targetptr="openjdk_postgresql_config">Configuring OpenJDK and
964 PostgreSQL in the <xi:include
965 href="../../s_docbuild/olinkdb/pardoc-names.xml"
966 xmlns:xi="http://www.w3.org/2001/XInclude"
967 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
968 Manual, for details on how to install and configure Java
969 OpenJDK.</para>
970
971 <para>Make sure the <literal>JAVA_HOME</literal> variable points to
972 the OpenJDK 11 installation:</para>
973
974 <programlisting>[root@localhost ~]# echo $JAVA_HOME
975/usr/lib/jvm/java-11-openjdk-11.0.10.0.9-0.el7_9.x86_64
976</programlisting>
977 </section>
978
979 <section id="ha_ucpe_mg">
980 <title>Installing the Enea Edge Management application in High
981 Availabilty mode</title>
982
983 <para>These steps must be taken on each of the CentOS 7 machines that
984 will host the Enea Edge Management application. It will be installed
985 and the setup for the external database cluster will be
986 prepared.</para>
987
988 <para>As the root user, go to the distribution folder of the Enea Edge
989 Management application, and run:</para>
990
991 <programlisting>[root@localhost distro]#./install.sh /opt/ \
992Enea_NFV_Access_uCPEManager_2.3.0-build23.tar.gz
993This will install the Enea Edge Management application into the /opt/ucpemanager folder.
994Select the following options, while asked by the installation script:
995Are you using the embedded PostgreSQL database? [Y/N]: <emphasis role="bold">N</emphasis>
996External database selected, getting user information ...
997Press 1 for PostgreSQL, 2 for MariaDB, 3 for SQL Server, 4 for Oracle and 5 \
998for MySQL: <emphasis role="bold">2</emphasis>
999Specify database server name(s) or IP Address(es): \
1000<emphasis role="bold">192.168.10.11,192.168.10.12,…,192.168.10.16 *(see note)</emphasis>
1001Specify database ID (or name) [ucpemanager]:
1002Specify database server port [3306]:
1003Specify database user name [root]: enea
1004Specify database password [root]: somepassword
1005Specify database startup thread pool size [1]:
1006Creating database configuration file \
1007/opt/ucpemanager/application/config/databaseConfig.xml ...
1008Done .
1009…
1010Installing ucpemanager service ..
1011Specify service username [ucpemanager]:
1012Specify service password [ucpemanager]: somepassword
1013…
1014Specify the IP address of the local interface: <emphasis role="bold">192.168.10.11</emphasis>
1015Is this server part of a cluster? [Y/N]: <emphasis role="bold">Y</emphasis>
1016Specify the name of the cluster [ucpemanager]:
1017Specify the shared (virtual) cluster IP address: <emphasis role="bold">192.168.10.10</emphasis>
1018Specify the netmask for the cluster IP address [255.255.255.0]:
1019Specify the IP address of the (optional) arbiter: <emphasis role="bold">192.168.10.13</emphasis>
1020Specify the port associated with the (optional) arbiter [3306]:
1021HA Configuration files modified successfully.
1022Configuration complete.</programlisting>
1023
1024 <note>
1025 <para>For each Enea Edge Management installation, place the local
1026 interface IP first in the list of IPs. This will optimize database
1027 communication, since the Enea Edge Management application uses the
1028 list of IPs sequentially, therefore using the internal loopback
1029 interface for communicating with the database.</para>
1030 </note>
1031
1032 <para>The arbiter IP and port are used to mitigate split brain
1033 situations. Providing an empty arbiter IP implies that no arbiter
1034 checking is enabled - in other words, it implies that arbiter
1035 connectivity is not checked. It is highly recommended to introduce an
1036 arbiter to help with split brain scenarios. For instance, one of the
1037 MariaDB cluster nodes can be used, with the default port
1038 <literal>3306</literal> (the MariaDB listening port).</para>
1039
1040 <para>Once the servers are up and running, log into the <emphasis
1041 role="bold">Primary</emphasis> and go to <emphasis
1042 role="bold">System</emphasis> and select <emphasis role="bold">Cluster
1043 View</emphasis>. The list of Enea Edge Management servers should be
1044 displayed, with one listed as Primary and the rest as Backup.</para>
1045
1046 <note><para>To avoid split-brain (network-partitioning) scenarios, it is possible
1047 for the user to specify an IP:port tuple for a system that acts as an
1048 Arbiter. In case both Primary and Backup servers cannot reach the Arbiter,
1049 there will be no Primary system to connect to and the management services
1050 will be unavailable.</para>
1051
1052 <para>This can be manually remedied by either fixing the network situation
1053 that caused the partitioning or modifying Arbiter information in the
1054 configuration file on the server that the user decides should be the
1055 (one and only) Primary server.</para></note>
1056
1057 <para><remark>ELCCR-907</remark>At times the VIP address is not
1058 acquired by any of the backup nodes if a power failure happens on
1059 primary node in a High Availability setup. To recover, follow the
1060 official documentation available at <ulink
1061 url="https://mariadb.com/kb/en/galera-cluster-recovery/">Galera
1062 Cluster Recovery</ulink>.</para>
1063
1064 <para>To change the configuration at a later point after the
1065 installation, either uninstall and then reinstall the product, or
1066 contact Enea Support.</para>
1067 </section>
1068 </section>
1069
1070 <section id="ha_upgrade">
1071 <title>Upgrading a High Availability Deployment</title>
1072
1073 <para>Upgrading a High Availabilty deployment is a highly complex,
1074 multi-step process that requires care to ensure both consistency and
1075 high-availability. Some steps need to be done manually.</para>
1076
1077 <orderedlist>
1078 <listitem>
1079 <para>We start with the assumption that
1080 <literal>EneaEdgeManagement-1 </literal>is the "PRIMARY"
1081 server.</para>
1082 </listitem>
1083
1084 <listitem>
1085 <para>Shut down database services on one side of the network, for
1086 example: MariaDB-4, MariaDB-5 and MariaDB-6.</para>
1087 </listitem>
1088
1089 <listitem>
1090 <para>Disconnect the network interfaces towards the VPN for machines
1091 MariaDB-4, MariaDB-5 and MariaDB-6. This will prevent any attempts
1092 at failover/synchronization.</para>
1093 </listitem>
1094
1095 <listitem>
1096 <para>Run the upgrade process on
1097 <literal>EneaEdgeManagement-3</literal> and
1098 <literal>EneaEdgeManagement-4</literal>. This will upgrade the
1099 service to the current release. Once the upgrade process completes,
1100 shutdown the Enea Edge Management service on both machines.</para>
1101 </listitem>
1102
1103 <listitem>
1104 <para>Disconnect the <literal>EneaEdgeManagement-2</literal> machine
1105 from the network (which will take MariaDB-2 offline as well). At
1106 this point, only the "PRIMARY" server is running, this is the start
1107 of the interval when we are susceptible to single-server
1108 failure.</para>
1109 </listitem>
1110
1111 <listitem>
1112 <para>Shutdown the MariaDB-2 process and run the Enea Edge
1113 Management upgrade process on
1114 <literal>EneaEdgeManagement-2</literal>. This will upgrade the
1115 service to the current release. Once the upgrade process completes,
1116 shutdown the Enea Edge Management service on the machine.</para>
1117 </listitem>
1118
1119 <listitem>
1120 <para>Reconnect the network interfaces towards the VPN for MariaDB-4
1121 (<literal>EneaEdgeManagement-3</literal>), MariaDB-5
1122 (<literal>EneaEdgeManagement-4</literal>) and MariaDB-6
1123 (<literal>EneaEdgeManagement-2</literal>). Restart database services
1124 on MariaDB-2, MariaDB-4, MariaDB-5 and MariaDB-6. This will allow
1125 database services on all machines to synchronize, any data that has
1126 been modified during the upgrade process will be made
1127 consistent.</para>
1128 </listitem>
1129
1130 <listitem>
1131 <para>Shutdown the "Primary" server
1132 (<literal>EneaEdgeManagement-1</literal>). At this point, the
1133 service is no longer available.</para>
1134 </listitem>
1135
1136 <listitem>
1137 <para>Start the Enea Edge Management service on
1138 <literal>EneaEdgeManagement-2</literal>. This machine will come up
1139 as the new "PRIMARY" with the upgraded software. As part of the
1140 startup process, it will upgrade the database and perform any other
1141 upgrade-related functionality.</para>
1142 </listitem>
1143
1144 <listitem>
1145 <para>At this point (once startup completes), service is available.
1146 However, the system is still susceptible to single-server
1147 failure.</para>
1148 </listitem>
1149
1150 <listitem>
1151 <para>Start the Enea Edge Management services on
1152 <literal>EneaEdgeManagement-3</literal> and
1153 <literal>EneaEdgeManagement-4</literal>. At this point, they will
1154 operate in highly-available mode.</para>
1155 </listitem>
1156
1157 <listitem>
1158 <para>Upgrade the Enea Edge Management application on
1159 <literal>EneaEdgeManagement-1</literal> (the one that has been shut
1160 down). Once that upgrade is complete and the service restarts, the
1161 entire setup has been upgraded to the new version.</para>
1162 </listitem>
1163 </orderedlist>
1164 </section>
1165 </section>
1166</chapter>
diff --git a/doc/book-enea-edge-getting-started/doc/book.xml b/doc/book-enea-edge-getting-started/doc/book.xml
new file mode 100644
index 0000000..07021cb
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/book.xml
@@ -0,0 +1,44 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4<!ENTITY % local.common.attrib "xml:base CDATA #IMPLIED">
5]>
6<book id="book_enea_edge_getting_started">
7 <title><trademark class="registered">Enea</trademark> Edge Getting
8 Started</title>
9
10 <subtitle>Release Version <xi:include
11 href="../../s_doceneacommon/doc/eltf_params_updated.xml"
12 xmlns:xi="http://www.w3.org/2001/XInclude"
13 xpointer="element(EneaLinux_REL_VER/1)" /></subtitle>
14
15 <!-- OLINKDBPATH_USED_BY_XMLMIND ../../s_docbuild/olinkdb -->
16
17 <xi:include href="../../s_docbuild/template/docsrc_common/bookinfo_userdoc.xml"
18 xmlns:xi="http://www.w3.org/2001/XInclude" />
19
20 <xi:include href="introduction.xml"
21 xmlns:xi="http://www.w3.org/2001/XInclude" />
22
23 <xi:include href="installation_guide.xml"
24 xmlns:xi="http://www.w3.org/2001/XInclude" />
25
26 <xi:include href="upgrade_ena.xml"
27 xmlns:xi="http://www.w3.org/2001/XInclude" />
28
29 <xi:include href="advanced_configurations.xml"
30 xmlns:xi="http://www.w3.org/2001/XInclude" />
31
32 <xi:include href="net_config_options.xml"
33 xmlns:xi="http://www.w3.org/2001/XInclude" />
34
35 <xi:include href="vnf_mg.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
36
37 <xi:include href="log_collector.xml"
38 xmlns:xi="http://www.w3.org/2001/XInclude" />
39
40 <xi:include href="grafana.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
41
42 <xi:include href="troubleshooting.xml"
43 xmlns:xi="http://www.w3.org/2001/XInclude" />
44</book> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/doc/grafana.xml b/doc/book-enea-edge-getting-started/doc/grafana.xml
new file mode 100644
index 0000000..807c2ac
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/grafana.xml
@@ -0,0 +1,361 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<chapter id="grafana">
3 <title>Using Grafana and InfluxDB</title>
4
5 <para><ulink url="https://docs.influxdata.com/influxdb/">InfluxDB</ulink> is
6 essentially a time series database process that runs on a server, while
7 <ulink url="https://grafana.com/docs/grafana">Grafana</ulink> is a
8 visualization tool for time series data. Grafana is a very lightweight
9 server-side application, and most of the data monitoring runs in a browser.</para>
10
11 <para>For details on version information for these two components, please refer to the
12 <ns:include href="../../s_docbuild/olinkdb/pardoc-common.xml"
13 xmlns:ns="http://www.w3.org/2001/XInclude"
14 xpointer="element(book_enea_edge_telemetry_open_source/1)" />.</para>
15
16 <section id="telemetry_deployment">
17 <title>Deploying Grafana and InfluxDB</title>
18
19 <para>Grafana and InfluxDB can be deployed using images for Docker on
20 linux. These images are provided by Enea along with a deploy script and
21 predefined dashboards. The Grafana and InfluxDB images can be deployed on
22 the same machine or on separate machines.</para>
23
24 <section id="prereq_deploy">
25 <title>Prerequisites for Deploying an Image</title>
26
27 <para>The following must be present in order to deploy an image:</para>
28
29 <itemizedlist>
30 <listitem>
31 <para>CentOS 7 Linux.</para>
32 </listitem>
33
34 <listitem>
35 <para>Internet connection for installing the Docker tool.</para>
36 </listitem>
37
38 <listitem>
39 <para>Root rights on the CentOS 7 machine.</para>
40 </listitem>
41 </itemizedlist>
42 </section>
43
44 <section id="docker_steps">
45 <title>Setting up Docker for Grafana and InfluxDB</title>
46
47 <para>In order to use the Grafana and InfluxDB containers, the Docker
48 tool that runs and manages containers needs to be available on the
49 server.</para>
50
51 <para>To install Docker on a CentOS 7 server open a terminal, log into a
52 bash shell with the root account and run the following commands:</para>
53
54 <orderedlist>
55 <listitem>
56 <para><literal>yum check-update</literal></para>
57 </listitem>
58
59 <listitem>
60 <para><literal>yum install -y yum-utils
61 device-mapper-persistent-data lvm2</literal></para>
62 </listitem>
63
64 <listitem>
65 <para><literal>yum-config-manager --add-repo
66 https://download.docker.com/linux/centos/docker-ce.repo</literal></para>
67 </listitem>
68
69 <listitem>
70 <para><literal>yum install docker</literal></para>
71 </listitem>
72 </orderedlist>
73
74 <para>In order to deploy the Grafana and InfluxDB images, the Docker
75 service needs to be started. To start the Docker service, log into a
76 bash shell with the root account and run the following command:
77 <literal>systemctl start docker</literal>.</para>
78
79 <note>
80 <para>By default, the Docker service is not configured to start at
81 boot. In order to configure it to autostart, log into a bash shell
82 with the root account and run the following command:
83 <literal>systemctl enable docker</literal>. The Grafana and InfluxDB
84 images are configured to autostart when the Docker service
85 starts.</para>
86 </note>
87 </section>
88
89 <section id="deploy_steps">
90 <title>Deploying Grafana and InfluxDB</title>
91
92 <para>On the CentOS 7 server open a terminal, log into a bash shell with
93 the root account and perform the following:</para>
94
95 <orderedlist>
96 <listitem>
97 <para>Extract
98 <filename>Enea_Edge_Telemetry_Deploy_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>.</para>
99
100 <para>The directory in which the archive will be unpacked will be
101 denoted as:
102 <literal>&lt;Telemetry-installerdir&gt;</literal>.</para>
103 </listitem>
104
105 <listitem>
106 <para>Enter
107 <literal>&lt;Telemetry-installerdir&gt;</literal>.</para>
108 </listitem>
109
110 <listitem>
111 <para>Run the provided <filename>telemetry_deploy.sh</filename>
112 script.</para>
113 </listitem>
114
115 <listitem>
116 <para>When prompted, select what images you want to deploy. Select
117 <literal>Both</literal> unless you wish for the Grafana and InfluxDB
118 images to be on separate servers.</para>
119
120 <note>
121 <para>If an image is already deployed, you will be prompted to
122 replace it.</para>
123
124 <para>By default, Grafana is configured for deployment on the same
125 server as InfluxDB. Please read the Grafana documentation on how
126 to configure it if you wish to deploy the images on separate
127 servers.</para>
128 </note>
129 </listitem>
130
131 <listitem>
132 <para>During the InfluxDB deployment, you will be prompted to
133 provide a username and password. These must match the ones
134 configured in the Enea Edge Management application for
135 Telemetry.</para>
136
137 <note>
138 <para>Changing the InfluxDB username and password requires
139 redeploying the InfluxDB image.</para>
140 </note>
141 </listitem>
142
143 <listitem>
144 <para>Verify the installation by running the command <literal>docker
145 ps -a</literal>. The Grafana and InfluxDB containers should be
146 present and have the status <literal>Up</literal>.</para>
147 </listitem>
148 </orderedlist>
149
150 <note>
151 <para>The provided Grafana instance by default uses the
152 <literal>Username:</literal> <emphasis role="bold">admin</emphasis>
153 and <literal>Password:</literal> <emphasis
154 role="bold">admin</emphasis>.</para>
155 </note>
156 </section>
157 </section>
158
159 <section id="telemetry_firewall_settings">
160 <title>Firewall settings for Grafana and InfluxDB</title>
161
162 <para>If a firewall is running on the machines where Grafana and InfluxDB
163 are deployed, this firewall needs to be configured so the required ports
164 are enabled.</para>
165
166 <para>To enable the ports, log into a bash shell with the root account and
167 perform the following:</para>
168
169 <orderedlist>
170 <listitem>
171 <para>For InfluxDB, run the following command:</para>
172
173 <programlisting>firewall-cmd --permanent --add-port=25826/tcp</programlisting>
174 </listitem>
175
176 <listitem>
177 <para>For Grafana, run the following command:</para>
178
179 <programlisting>firewall-cmd --permanent --add-port=3000/tcp</programlisting>
180 </listitem>
181 </orderedlist>
182 </section>
183
184 <section id="grafana_settings">
185 <title>Setting Grafana and InfluxDB parameters</title>
186
187 <para>Customizing InfluxDB and Grafana parameters can be done in the Enea
188 Edge Management GUI by selecting the <emphasis
189 role="bold">System</emphasis> menu, then <emphasis
190 role="bold">Configuration</emphasis>, accessing the <emphasis
191 role="bold">Properties</emphasis> tab, and clicking on the <emphasis
192 role="bold">Telemetry</emphasis> tab. The settings that can be changed are
193 listed in the table below:</para>
194
195 <table>
196 <title>Telemetry settings</title>
197
198 <tgroup cols="3">
199 <colspec align="left" colname="1" colwidth="1*" />
200
201 <colspec align="left" colname="2" colwidth="3*" />
202
203 <colspec align="left" colname="3" colwidth="1*" />
204
205 <tbody>
206 <row>
207 <entry><emphasis role="bold">Field name</emphasis></entry>
208
209 <entry><emphasis role="bold">Description</emphasis></entry>
210
211 <entry><emphasis role="bold">Default value</emphasis></entry>
212 </row>
213
214 <row>
215 <entry>Grafana Hostname or IP Address</entry>
216
217 <entry>The public hostname or IP address where the Grafana
218 instance is installed.</entry>
219
220 <entry>no default</entry>
221 </row>
222
223 <row>
224 <entry>Grafana Port</entry>
225
226 <entry>The port Grafana uses.</entry>
227
228 <entry>3000</entry>
229 </row>
230
231 <row>
232 <entry>Grafana Dashboard</entry>
233
234 <entry>The dashboard that should be used when opening Grafana
235 using the Enea Edge Management application.</entry>
236
237 <entry>host</entry>
238 </row>
239
240 <row>
241 <entry>InfluxDB Hostname or IP Address</entry>
242
243 <entry>The public hostname or IP address where the InfluxDB
244 database is installed.</entry>
245
246 <entry>no default</entry>
247 </row>
248
249 <row>
250 <entry>InfluxDB Port</entry>
251
252 <entry>The port used for communication between InfluxDB and the
253 Telemetry server.</entry>
254
255 <entry>25826</entry>
256 </row>
257
258 <row>
259 <entry>InfluxDB Username</entry>
260
261 <entry>The username used for encrypting communication between
262 InfluxDB and the Telemetry server.</entry>
263
264 <entry>admin0</entry>
265 </row>
266
267 <row>
268 <entry>InfluxDB Password</entry>
269
270 <entry>The password used for encrypting communication between
271 InfluxDB and the Telemetry server.</entry>
272
273 <entry>admin</entry>
274 </row>
275 </tbody>
276 </tgroup>
277 </table>
278
279 <para>When changing any of the settings in the <emphasis
280 role="bold">Telemetry</emphasis> tab, the Enea Edge Management application
281 will inform all uCPE devices of the change if they have telemetry
282 running.</para>
283
284 <figure>
285 <title>Telemetry Properties</title>
286
287 <mediaobject>
288 <imageobject>
289 <imagedata contentwidth="615"
290 fileref="images/telemetry_settings.png" />
291 </imageobject>
292 </mediaobject>
293 </figure>
294 </section>
295
296 <section id="telemetry_start_stop">
297 <title>Starting and stopping Telemetry</title>
298
299 <para>When a uCPE Device is selected, in the <emphasis
300 role="bold">Operations</emphasis> menu, the <emphasis role="bold">Start
301 Telemetry</emphasis> and <emphasis role="bold">Stop Telemetry</emphasis>
302 options are available.</para>
303
304 <para>When starting Telemetry for a uCPE device, the Enea Edge Management
305 application sends the following information about the InfluxDB:</para>
306
307 <itemizedlist>
308 <listitem>
309 <para>The IP address and hostname where InfluxDB is installed.</para>
310 </listitem>
311
312 <listitem>
313 <para>The port used for communication between InfluxDB and the
314 Telemetry server.</para>
315 </listitem>
316
317 <listitem>
318 <para>The credentials used for encrypting communication between
319 InfluxDB and the Telemetry server.</para>
320 </listitem>
321 </itemizedlist>
322
323 <para>These fields are read-only and are populated with the values already
324 set in the <emphasis role="bold">System Configuration</emphasis>. If one
325 of the fields is not set or if it does not have the desired value, modify
326 it in the <emphasis role="bold">System Configuration</emphasis>. The
327 password is sent encrypted using the Base64 scheme.</para>
328
329 <figure>
330 <title>Telemetry Start Dialog</title>
331
332 <mediaobject>
333 <imageobject>
334 <imagedata contentwidth="615" fileref="images/telemetry_start.png" />
335 </imageobject>
336 </mediaobject>
337 </figure>
338
339 <para>When the Telemetry status is changed on a uCPE device, a
340 notification is sent to the Enea Edge Management application. These
341 notifications can be inspected under <emphasis
342 role="bold">Fault</emphasis> found in the <emphasis
343 role="bold">Event</emphasis> menu.</para>
344 </section>
345
346 <section id="grafana_launch">
347 <title>Launching Grafana</title>
348
349 <para>When a uCPE Device is selected, the <emphasis
350 role="bold">Telemetry</emphasis> button is available. Pressing this button
351 will open a new window pointing to Grafana. The current uCPE device will
352 be selected in Grafana.</para>
353
354 <para>The hostname or IP Address and the port of the Grafana installation
355 can be customized by selecting <emphasis role="bold">System</emphasis>,
356 then the <emphasis role="bold">Configuration</emphasis> menu, accessing
357 the <emphasis role="bold">Properties</emphasis> tab, and clicking on the
358 <emphasis role="bold">Telemetry</emphasis> tab. The default dashboard
359 available when launching Grafana can be customized as well.</para>
360 </section>
361</chapter> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/doc/images/archive_list.png b/doc/book-enea-edge-getting-started/doc/images/archive_list.png
new file mode 100755
index 0000000..302f32d
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/archive_list.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/collect_debug_logs.png b/doc/book-enea-edge-getting-started/doc/images/collect_debug_logs.png
new file mode 100755
index 0000000..6582737
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/collect_debug_logs.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/debug_settings.png b/doc/book-enea-edge-getting-started/doc/images/debug_settings.png
new file mode 100755
index 0000000..2c97b2c
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/debug_settings.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/dev_file_mg.png b/doc/book-enea-edge-getting-started/doc/images/dev_file_mg.png
new file mode 100755
index 0000000..a4a4f5c
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/dev_file_mg.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/download_files.png b/doc/book-enea-edge-getting-started/doc/images/download_files.png
new file mode 100755
index 0000000..cb686e4
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/download_files.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/edit_inter.png b/doc/book-enea-edge-getting-started/doc/images/edit_inter.png
new file mode 100755
index 0000000..fddde37
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/edit_inter.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/edit_inter_config.png b/doc/book-enea-edge-getting-started/doc/images/edit_inter_config.png
new file mode 100755
index 0000000..f9ab8aa
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/edit_inter_config.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/fault_events.png b/doc/book-enea-edge-getting-started/doc/images/fault_events.png
new file mode 100755
index 0000000..aeec955
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/fault_events.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/high_av_setup.png b/doc/book-enea-edge-getting-started/doc/images/high_av_setup.png
new file mode 100644
index 0000000..d119ecb
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/high_av_setup.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/onboard_a_vnf_image.png b/doc/book-enea-edge-getting-started/doc/images/onboard_a_vnf_image.png
new file mode 100755
index 0000000..da52202
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/onboard_a_vnf_image.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/ovs_bridges_tab.png b/doc/book-enea-edge-getting-started/doc/images/ovs_bridges_tab.png
new file mode 100755
index 0000000..0b3ec54
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/ovs_bridges_tab.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/prep_deploy.png b/doc/book-enea-edge-getting-started/doc/images/prep_deploy.png
new file mode 100755
index 0000000..2db2487
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/prep_deploy.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/prep_execution.png b/doc/book-enea-edge-getting-started/doc/images/prep_execution.png
new file mode 100755
index 0000000..404760b
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/prep_execution.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/telemetry_settings.png b/doc/book-enea-edge-getting-started/doc/images/telemetry_settings.png
new file mode 100644
index 0000000..276b716
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/telemetry_settings.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/telemetry_start.png b/doc/book-enea-edge-getting-started/doc/images/telemetry_start.png
new file mode 100644
index 0000000..81510b5
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/telemetry_start.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/vnf_space.png b/doc/book-enea-edge-getting-started/doc/images/vnf_space.png
new file mode 100755
index 0000000..57ed581
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/vnf_space.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/wap_external_interface.png b/doc/book-enea-edge-getting-started/doc/images/wap_external_interface.png
new file mode 100644
index 0000000..ee49fc1
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/wap_external_interface.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/images/wap_wireless_ap.png b/doc/book-enea-edge-getting-started/doc/images/wap_wireless_ap.png
new file mode 100644
index 0000000..b7c77bf
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/wap_wireless_ap.png
Binary files differ
diff --git a/doc/book-enea-edge-getting-started/doc/installation_guide.xml b/doc/book-enea-edge-getting-started/doc/installation_guide.xml
new file mode 100644
index 0000000..477b5c4
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/installation_guide.xml
@@ -0,0 +1,1255 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<chapter id="installation_guide">
3 <title>Setting up and Installing the Enea Edge Base Configuration</title>
4
5 <para>The setup and installation steps detailed below will deploy a base
6 configuration which will be used as a reference for more complex deployment
7 scenarios.</para>
8
9 <section id="hw_reqs">
10 <title>Hardware Requirements</title>
11
12 <para>The following hardware is needed for deploying the base
13 configuration:</para>
14
15 <itemizedlist>
16 <listitem>
17 <para>One server running the CentOS 7 distribution</para>
18
19 <note>
20 <para>The CentOS 7 server must be updated to the latest revision
21 before installing Enea Edge, and configured for English language
22 usage.</para>
23 </note>
24
25 <para>The following will detail CPU, RAM and storage requirements for
26 the Enea Edge Management application:</para>
27
28 <itemizedlist>
29 <listitem>
30 <para>For small-sized deployments (tens of devices):</para>
31
32 <itemizedlist spacing="compact">
33 <listitem>
34 <para>4 cores</para>
35 </listitem>
36
37 <listitem>
38 <para>16 GB RAM</para>
39 </listitem>
40
41 <listitem>
42 <para>300 GB single disk storage</para>
43 </listitem>
44 </itemizedlist>
45 </listitem>
46
47 <listitem>
48 <para>For mid-sized deployments (hundreds of devices):</para>
49
50 <itemizedlist spacing="compact">
51 <listitem>
52 <para>8 cores</para>
53 </listitem>
54
55 <listitem>
56 <para>32 GB RAM</para>
57 </listitem>
58
59 <listitem>
60 <para>300 GB single disk storage</para>
61 </listitem>
62 </itemizedlist>
63 </listitem>
64
65 <listitem>
66 <para>For large deployments (thousands of devices):</para>
67
68 <itemizedlist spacing="compact">
69 <listitem>
70 <para>16 cores</para>
71 </listitem>
72
73 <listitem>
74 <para>64-256 GB RAM</para>
75 </listitem>
76
77 <listitem>
78 <para>1-2 TB single disk storage</para>
79 </listitem>
80 </itemizedlist>
81 </listitem>
82 </itemizedlist>
83
84 <para>The purpose of the CentOS 7 server is to host the Enea Edge
85 Management application. Network access between the CentOS 7 server and
86 the uCPE devices is required. The Enea Edge Management application and
87 the uCPE devices will be connected on separate subnets to avoid
88 inconsistencies.</para>
89 </listitem>
90
91 <listitem>
92 <para>One or more uCPE devices.</para>
93
94 <para>Whitebox devices where the Enea Edge Runtime will be installed,
95 containing a minimum of 2 cores and 4 GB RAM and at least two ethernet
96 ports that will be configured as WAN and LAN during deployment.</para>
97
98 <para>When hosting an entire solution including one or several network
99 services, the hardware must also have the resources to host one or
100 more VNFs. During a typical evaluation, a dual VNF service on the Enea
101 Edge Runtime needs a CPU with 4-8 cores and at least 8 GB RAM. The
102 supported Intel CPUs of Enea Edge are documented in the <xi:include
103 href="../../s_docbuild/olinkdb/pardoc-common.xml"
104 xmlns:xi="http://www.w3.org/2001/XInclude"
105 xpointer="element(book_enea_edge_release_info/1)" /> Manual.</para>
106
107 <para>Enea Edge Runtime needs EFI support in BIOS to boot. When
108 configuring the uCPE device BIOS a serial connection is
109 required.</para>
110 </listitem>
111
112 <listitem>
113 <para>A laptop.</para>
114
115 <para>The laptop is used for 2 scenarios:</para>
116
117 <itemizedlist>
118 <listitem>
119 <para>Installing the Enea Edge Runtime on uCPE Devices.</para>
120 </listitem>
121
122 <listitem>
123 <para>Connecting to the GUI of the Enea Edge Management
124 application for management and configuration. Network access
125 between the CentOS 7 server and the laptop is required. Please see
126 the <xi:include href="../../s_docbuild/olinkdb/pardoc-common.xml"
127 xmlns:xi="http://www.w3.org/2001/XInclude"
128 xpointer="element(book_enea_edge_release_info/1)" /> Manual
129 available with your release, for recommended browsers.</para>
130 </listitem>
131 </itemizedlist>
132 </listitem>
133
134 <listitem>
135 <para>A 16 GB USB stick used for the uCPE Device Installation.</para>
136 </listitem>
137 </itemizedlist>
138 </section>
139
140 <section id="sw_config">
141 <title>Software Configuration</title>
142
143 <para>The CentOS 7 server requires a specific configuration for the setup
144 to work.</para>
145
146 <section id="firewall_config">
147 <title>Firewall Configuration</title>
148
149 <para>Any firewall running on the CentOS 7 server may block the
150 management protocols required to communicate between the uCPE device and
151 the Enea Edge Management application as well as between the Enea Edge
152 Management application and its northbound clients. Quick handling of a
153 blocking firewall would be to disable it, typical for a lab environment,
154 through:</para>
155
156 <programlisting>sudo systemctl stop firewalld
157sudo systemctl disable firewalld
158sudo systemctl mask now firewalld</programlisting>
159
160 <para>For an advanced firewall configuration, the following ports need
161 to be opened:</para>
162
163 <table>
164 <title>Ports to be Activated</title>
165
166 <tgroup cols="3">
167 <colspec align="left" />
168
169 <tbody>
170 <row>
171 <entry>80</entry>
172
173 <entry>TCP</entry>
174
175 <entry>Required for GUI Access.</entry>
176 </row>
177
178 <row>
179 <entry>443</entry>
180
181 <entry>TCP</entry>
182
183 <entry>Required for GUI Access and Device Connectivity.</entry>
184 </row>
185
186 <row>
187 <entry>54327</entry>
188
189 <entry>UDP</entry>
190
191 <entry>Required for the Enea Edge Management application High
192 Availability Configuration.</entry>
193 </row>
194
195 <row>
196 <entry>5701:5708</entry>
197
198 <entry>TCP</entry>
199
200 <entry>Required for the Enea Edge Management application High
201 Availability Configuration.</entry>
202 </row>
203
204 <row>
205 <entry>4334</entry>
206
207 <entry>TCP</entry>
208
209 <entry>Required for Call Home.</entry>
210 </row>
211
212 <row>
213 <entry>2021:2040</entry>
214
215 <entry>TCP</entry>
216
217 <entry>Required for Call Home when connecting uCPE Devices using
218 Enea NFV Access 2.3.0 or older.</entry>
219 </row>
220 </tbody>
221 </tgroup>
222 </table>
223
224 <para>Use the following command sequence to enable the required ports
225 for deployment of the Enea Edge Management application:</para>
226
227 <programlisting>sudo firewall-cmd --permanent --add-port=80/tcp
228sudo firewall-cmd --permanent --add-port=443/tcp
229sudo firewall-cmd --permanent --add-port=54327/udp
230sudo firewall-cmd --permanent --add-port=5701-5708/tcp
231sudo firewall-cmd --permanent --add-port=4334/tcp
232sudo firewall-cmd --permanent --add-port=2021-2040/tcp
233sudo firewall-cmd --reload</programlisting>
234
235 <note>
236 <para>If the Enea Edge Management host resides behind a corporate
237 port-filtering firewall, then all the aforementioned ports need to
238 also be enabled on the respective firewall. As an additional
239 requirement, port 22/TCP also needs to be enabled for reverse SSH to
240 the Enea Edge Management application.</para>
241
242 <para>No enabling and no forwarding rules are necessary for ports
243 2021-2040 if Enea Edge 2.4.0 or newer is used.</para>
244 </note>
245 </section>
246
247 <section id="openjdk_postgresql_config">
248 <title>Configuring OpenJDK and PostgreSQL</title>
249
250 <para>The Enea Edge Management application requires a specific Java
251 version (OpenJDK 11) and a PostgreSQL version to operate
252 correctly.</para>
253
254 <para><emphasis role="bold">Installing OpenJDK</emphasis></para>
255
256 <orderedlist spacing="compact">
257 <listitem>
258 <para>Install OpenJDK 11 using the root account:</para>
259
260 <programlisting>yum install java-11-openjdk-devel</programlisting>
261 </listitem>
262
263 <listitem>
264 <para>Verify the installation:</para>
265
266 <programlisting>java -version
267openjdk version "11.0.3" 2019-04-16 LTS
268OpenJDK Run Time Environment 18.9 (build 11.0.3+7-LTS)
269OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing)</programlisting>
270
271 <note>
272 <para>If there are multiple java versions installed, switch
273 between them using the following command:</para>
274
275 <programlisting>alternatives --config java</programlisting>
276
277 <para>Optionally, the user can switch between the
278 <literal>javac</literal> versions using:</para>
279
280 <programlisting>alternatives --config javac</programlisting>
281 </note>
282 </listitem>
283
284 <listitem>
285 <para>The following system variables need to point to the OpenJDK 11
286 installation:</para>
287
288 <programlisting>export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which java)))))
289export PATH=$PATH:$JAVA_HOME/bin
290export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar</programlisting>
291
292 <note>
293 <para>In order to make these system variables persistent, the
294 commands given above should be added to a script in the
295 <literal>/etc/profile.d/</literal> folder. <emphasis
296 role="bold">Sudo</emphasis> access is needed for this
297 operation.</para>
298 </note>
299 </listitem>
300 </orderedlist>
301
302 <para>The Enea Edge Management application requires a specific
303 PostgreSQL version. This is embedded in the Enea Edge Management
304 installation. In order to avoid conflicts, any existing PostgreSQL
305 installation needs to be uninstalled.</para>
306
307 <para><emphasis role="bold">Uninstalling PostgreSQL</emphasis></para>
308
309 <orderedlist>
310 <listitem>
311 <para>Open a terminal with administrative rights, i.e. log into a
312 bash shell with root privileges.</para>
313 </listitem>
314
315 <listitem>
316 <para>Execute the following command to check if you have a currently
317 running PostgreSQL database server:</para>
318
319 <programlisting>ps -ef | grep post</programlisting>
320 </listitem>
321
322 <listitem>
323 <para>Remove the installed PostgreSQL server (including the existing
324 postgres user):</para>
325
326 <note>
327 <para>This step is not necessary if the Enea Edge Management
328 application will be using an external database (like
329 MariaDB).</para>
330 </note>
331
332 <programlisting>yum remove postgres\*
333rm -rf /var/lib/pgsql
334rm -f /etc/postgres-reg.ini
335userdel postgres</programlisting>
336 </listitem>
337 </orderedlist>
338
339 <para>If you have multiple spindles, it is recommended to let the
340 application run off one and the database off the other. This will result
341 in optimum performance. It is also recommended that the swap disk be the
342 same as the one used for the application.</para>
343
344 <para>Assuming another spindle is used (<literal>/drive2</literal>) do
345 the following:</para>
346
347 <orderedlist>
348 <listitem>
349 <para>Create a folder which will host the database (e.g.
350 <literal>emsDatabase</literal>).</para>
351 </listitem>
352
353 <listitem>
354 <para>Create a soft-link that will point to this folder:</para>
355
356 <programlisting>ln -s /opt/ems/elementcenter/database /drive2/emsDatabase</programlisting>
357 </listitem>
358
359 <listitem>
360 <para>Follow the installation steps for the Enea Edge Management
361 application available in <olink
362 targetdoc="book_enea_edge_getting_started"
363 targetptr="install_ucpe_mg">Installing the Enea Edge Management
364 application in the <xi:include
365 href="../../s_docbuild/olinkdb/pardoc-names.xml"
366 xmlns:xi="http://www.w3.org/2001/XInclude"
367 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
368 Manual.</para>
369 </listitem>
370 </orderedlist>
371 </section>
372 </section>
373
374 <section id="ucpe_config">
375 <title>uCPE Device Configuration</title>
376
377 <section id="wan_lan_ports">
378 <title>Determining the WAN and LAN ports</title>
379
380 <para>A typical whitebox comes with multiple physical network ports,
381 ready to be used. The user must determine the purpose and allocation of
382 each port. The allocation is later aligned with the software
383 configuration within the Web-installer.</para>
384
385 <para>A common way is to allocate the left ports to WANs and the right
386 ports to LANs. At least one port must be allocated to WAN and one to
387 LAN.</para>
388 </section>
389
390 <section id="ucpe_identifier">
391 <title>Determining the Device ID</title>
392
393 <para>Each uCPE device needs a unique identifier. This identifier is
394 used to match the registration in the Enea Edge Management application
395 and the offline configuration of the uCPE device during ZTP (Zero Touch
396 Provisioning).</para>
397
398 <para>Select a text string to represent the uCPE device, e.g.
399 <literal>uCPE-1</literal> or <literal>fwa-t1012vc_boston_1234</literal>.
400 It can have any length and any type of characters with the exception of
401 quotation characters (' or ") or line terminators (\n or \r).</para>
402 </section>
403
404 <section id="bios_config">
405 <title>Configuring the BIOS</title>
406
407 <para>The factory configuration of the BIOS may not match the
408 requirements of Enea Edge Runtime. The BIOS configuration needs to be
409 reviewed and potentially reconfigured to prepare for a successful
410 installation.</para>
411
412 <para>Access the BIOS using a serial cable between the uCPE device and
413 the laptop, to review and configure the BIOS correctly. The whitebox
414 vendor is expected to provide the right serial cable for the box. A
415 terminal emulator (such as putty) is needed on the laptop.</para>
416
417 <para>Enable the following BIOS features/configurations:</para>
418
419 <itemizedlist>
420 <listitem>
421 <para>EFI</para>
422 </listitem>
423
424 <listitem>
425 <para>Intel Virtualization Technology (VT-x)</para>
426 </listitem>
427
428 <listitem>
429 <para>Intel Virtualization Technology for Directed I/O (VT-d)</para>
430 </listitem>
431
432 <listitem>
433 <para>SR-IOV</para>
434 </listitem>
435 </itemizedlist>
436
437 <para>The boot order may also need to be modified to support
438 installation and execution of the Enea Edge Runtime on the uCPE
439 device.</para>
440
441 <para>The following boot order is recommended for a base
442 configuration:</para>
443
444 <orderedlist>
445 <listitem>
446 <para>Boot from USB</para>
447 </listitem>
448
449 <listitem>
450 <para>Boot from Disk</para>
451 </listitem>
452 </orderedlist>
453
454 <para>By arranging the above boot order there is no need for a further
455 configuration of the BIOS during installation and deployment.</para>
456 </section>
457 </section>
458
459 <section id="prep_deploy">
460 <title>Preparing the Deployment</title>
461
462 <section id="install_ucpe_mg">
463 <title>Installing the Enea Edge Management application</title>
464
465 <para>The Enea Edge Management application can be installed using a
466 fresh (first-time) configuration or using a backup file of a previous
467 installation, created within the Enea Edge Management GUI.</para>
468
469 <section id="fresh_ucpemg_install">
470 <title>Fresh Installation of the Enea Edge Management
471 application</title>
472
473 <para>On the CentOS 7 server open a terminal, log into a bash shell
474 with the root account and perform the following:</para>
475
476 <orderedlist>
477 <listitem>
478 <para>Extract
479 <literal>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</literal></para>
480
481 <para>The directory in which the archive has been unpacked will be
482 denoted as: <literal>&lt;uCPEM-installerdir&gt;</literal>.</para>
483 </listitem>
484
485 <listitem>
486 <para>Enter
487 <literal>&lt;uCPEM-installerdir&gt;/dist</literal>.</para>
488 </listitem>
489
490 <listitem>
491 <para>Choose the target installation folder, e.g.
492 <literal>/opt/ems</literal>. Everything will be installed under a
493 folder called <literal>/ucpemanager</literal> within the target
494 installation folder.</para>
495
496 <para>The application files will be installed in
497 <literal>/opt/ems/ucpemanager/application</literal>. The database
498 will be installed in
499 <literal>/opt/ems/ucpemanager/database</literal>.</para>
500 </listitem>
501
502 <listitem>
503 <para>Run the following interactive command:</para>
504
505 <programlisting>./install.sh /opt/ems \
506Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
507
508 <para>The default configuration values are specified in brackets.
509 If no other value is preferred and typed in, pressing
510 <literal>ENTER</literal> will keep the default values. When there
511 is an option within parentheses (i.e.Y/N), a value must be
512 specified.</para>
513
514 <note>
515 <para>The same configuration values set now will need to be
516 provided when upgrading or uninstalling the Enea Edge Management
517 application.</para>
518 </note>
519
520 <itemizedlist>
521 <listitem>
522 <para>Database Configurations:</para>
523
524 <itemizedlist spacing="compact">
525 <listitem>
526 <para>Are you using the embedded PostgreSQL database?
527 [Y/N]: <literal>Y</literal>.</para>
528 </listitem>
529
530 <listitem>
531 <para>Specify the database process password
532 <literal>[postgres]</literal>:</para>
533 </listitem>
534
535 <listitem>
536 <para>Specify the database ID (or name)
537 <literal>[ucpemanager]</literal>:</para>
538 </listitem>
539
540 <listitem>
541 <para>Specify the database server port
542 <literal>[5432]</literal>:</para>
543 </listitem>
544
545 <listitem>
546 <para>Specify a database user name
547 <literal>[postgres]</literal>:</para>
548 </listitem>
549
550 <listitem>
551 <para>Specify a database password
552 <literal>[postgres]</literal>:</para>
553 </listitem>
554
555 <listitem>
556 <para>Specify the database startup thread pool size
557 <literal>[1]</literal>:</para>
558 </listitem>
559 </itemizedlist>
560 </listitem>
561
562 <listitem>
563 <para>Service Configurations:</para>
564
565 <itemizedlist spacing="compact">
566 <listitem>
567 <para>Specify a service username
568 <literal>[ucpemanager]:</literal></para>
569 </listitem>
570
571 <listitem>
572 <para>Specify a service password
573 <literal>[ucpemanager]</literal>:</para>
574 </listitem>
575 </itemizedlist>
576 </listitem>
577
578 <listitem>
579 <para>High Availability Configurations:</para>
580
581 <itemizedlist spacing="compact">
582 <listitem>
583 <para>Specify the IP address of the local interface: The
584 CentOS 7 Server loopback address:
585 <literal>127.0.0.1</literal>.</para>
586 </listitem>
587
588 <listitem>
589 <para>Is this server part of a cluster? [Y/N]:
590 <literal>N</literal>.</para>
591 </listitem>
592 </itemizedlist>
593 </listitem>
594
595 <listitem>
596 <para>Create the self-signed certificate: <literal>Specify IP or domain name</literal>
597 (or press <literal>Enter</literal> to skip):</para>
598
599 <para>The Tomcat self-signed certificate can be generated
600 again by running the
601 <filename>createCertificate.sh</filename>. For more details, please see <olink
602 targetdoc="book_enea_edge_getting_started"
603 targetptr="create_certificate">Tomcat Certificate
604 Generation in the <ns:include
605 href="../../s_docbuild/olinkdb/pardoc-names.xml"
606 xpointer="element(book_enea_edge_getting_started/1)"
607 xmlns:ns="http://www.w3.org/2001/XInclude" /></olink> Manual.</para>
608
609 <note>
610 <para>The generation of the Tomcat self-signed cerificate
611 should be skipped only if another certifcate will be
612 provided.</para>
613 </note>
614 </listitem>
615
616 <listitem>
617 <para>Heap Configuration:</para>
618
619 <itemizedlist spacing="compact">
620 <listitem>
621 <para>Please enter the new Maximum Heap Size
622 [4g]:</para>
623 </listitem>
624 </itemizedlist>
625 </listitem>
626 </itemizedlist>
627
628 <para>This command will:</para>
629
630 <itemizedlist spacing="compact">
631 <listitem>
632 <para>Extract the application files from the compressed
633 installation kit.</para>
634 </listitem>
635
636 <listitem>
637 <para>Install the bundled database.</para>
638 </listitem>
639
640 <listitem>
641 <para>Install the Enea Edge Management application as a
642 service with the name <literal>ucpemanager</literal>.</para>
643 </listitem>
644
645 <listitem>
646 <para>Start the <literal>ucpemanager</literal> service.</para>
647 </listitem>
648 </itemizedlist>
649 </listitem>
650
651 <listitem>
652 <para>Using the IPv4 address of the CentOS 7 Server in a web
653 browser, running on the laptop, log into the Enea Edge Management
654 GUI using the default username and password:
655 <literal>admin/admin</literal>.</para>
656 </listitem>
657 </orderedlist>
658
659 <note>
660 <para>The IPv4 address of the CentOS 7 Server will be used as a configuration
661 parameter when setting up the uCPE devices.</para>
662
663 <para>If the CentOS 7 Server is installed behind NAT, the IPv4
664 address used will be the public IP of the NAT device and port
665 forwarding rules must be created to ensure the uCPE device can
666 access the Enea Edge Management application. For more details,
667 please see <link linkend="firewall_config">Firewall
668 Configuration</link>.</para>
669 </note>
670 </section>
671
672 <section id="install_ucpemg_from_backup">
673 <title>Installation of the Enea Edge Management application using a
674 System Back-up</title>
675
676 <para>The Enea Edge Management application can be restored if a backup
677 file has been previously created.</para>
678
679 <para>A backup file can be created by accessing the <emphasis
680 role="bold">System</emphasis> menu, and clicking <emphasis
681 role="bold">System Backup</emphasis>, from the Enea Edge Management
682 GUI. The resulting zip archive will be located in the
683 <filename>/opt/ems/ucpemanager/application/backup</filename> folder
684 and will be named
685 <literal>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</literal> (e.g
686 System-Backup_Feb19_2013_2257_42.zip). Save the archive to another
687 location outside the Enea Edge Management installation folder for
688 future use.</para>
689
690 <note>
691 <para>The System Back-up file obtained from the Enea Edge Management
692 GUI (<filename>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</filename>) is
693 different from the snapshot obtained during an Enea Edge Management
694 Upgrade or Uninstall operation
695 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>) needed
696 for recovery of the Enea Edge Management application. For more
697 details, see <olink targetdoc="book_enea_edge_getting_started"
698 targetptr="restore_prev_ucpe_install">Restoring a previous Enea Edge
699 Management installation in the <xi:include
700 href="../../s_docbuild/olinkdb/pardoc-names.xml"
701 xmlns:xi="http://www.w3.org/2001/XInclude"
702 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
703 Manual.</para>
704 </note>
705
706 <para>To install the Enea Edge Management application with the restore
707 option provide an additional argument as shown below during
708 installation:</para>
709
710 <programlisting>./install.sh \
711/opt/ems Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz \
712SystemBackup_MMMDD_YYYY_HHMM_SS.zip</programlisting>
713 </section>
714 </section>
715
716 <section id="prep_usb_ena">
717 <title>Preparing the USB stick for installation of the Enea Edge
718 Runtime</title>
719
720 <para>To install the Enea Edge Runtime, create a bootable USB stick with
721 the image you intend to install.</para>
722
723 <para>In the example below, step by step instructions are provided for
724 the CentOS 7 distribution. It's possible with the appropriate tools to
725 also use Windows OS or MacOS.</para>
726
727 <note>
728 <para>The <filename>.hddimg</filename> image is available in the
729 <filename>Enea_Edge_Runtime_&lt;processor&gt;_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
730 file you downloaded with your release.</para>
731 </note>
732
733 <para><emphasis role="bold">Create a bootable USB stick
734 image</emphasis></para>
735
736 <orderedlist>
737 <listitem>
738 <para>Copy the <filename>.hddimg</filename> image file provided by
739 Enea, onto the CentOS 7 server.</para>
740 </listitem>
741
742 <listitem>
743 <para>Connect the USB stick to the CentOS 7 Server and identify the
744 USB device name given by the system with
745 <literal>lsblk</literal>:</para>
746
747 <programlisting>NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
748sda 8:0 1 28.7G 0 disk
749sdb 8:0 0 111.8G 0 disk
750|-sdb1 8:1 0 111.8G 0 part</programlisting>
751 </listitem>
752
753 <listitem>
754 <para>Copy the <filename>.hddimg</filename> image onto the USB
755 stick, e.g:</para>
756
757 <programlisting>sudo dd if=./enea-nfv-access-&lt;machine&gt;.hddimg \
758of=/dev/sdb bs=4M conv=fsync</programlisting>
759
760 <para>Where <filename>enea-nfv-access-&lt;machine&gt;.hddimg</filename> is
761 the <filename>.hddimg</filename> file and <literal>sdb</literal> is
762 the assigned USB device name.</para>
763 </listitem>
764 </orderedlist>
765 </section>
766
767 <section id="prep_phys_deploy">
768 <title>Preparing Physical Deployment for Installation</title>
769
770 <figure>
771 <title>Preparing for Hardware Installation</title>
772
773 <mediaobject>
774 <imageobject>
775 <imagedata contentwidth="600" fileref="images/prep_deploy.png" />
776 </imageobject>
777 </mediaobject>
778 </figure>
779
780 <para>While the uCPE device is powered off, in order to install and
781 configure the Enea Edge Runtime (using the prepared USB stick), connect
782 the laptop to a uCPE device LAN port. For this purpose, a Layer 2 switch
783 or direct cable connection can be used.</para>
784 </section>
785
786 <section id="install_ena_device">
787 <title>Installing Enea Edge - uCPE Device Installation</title>
788
789 <para>To initiate the installation of the Enea Edge Runtime do the
790 following:</para>
791
792 <orderedlist>
793 <listitem>
794 <para>Plug the USB stick into the uCPE device.</para>
795 </listitem>
796
797 <listitem>
798 <para>Power up the uCPE device and boot the USB stick.</para>
799 </listitem>
800
801 <listitem>
802 <para>The Web-installer application will start automatically and can
803 be accessed in a web browser on the laptop at
804 <literal>http://172.16.1.1</literal> (port 80).</para>
805 </listitem>
806
807 <listitem>
808 <para>On the <emphasis role="bold">Requirements</emphasis> page of
809 the Web-installer, the user must confirm the the current state of
810 the installation prerequisites is inline with the desired
811 state:</para>
812
813 <itemizedlist>
814 <listitem>
815 <para>Requirements table. Minimum values apply to the
816 installation process only. For runtime operations, additional
817 resources should be available depending on the specific
818 workload. Requirements are color coded (green when met, red when
819 mandatory and not met, orange when optional and not met). The
820 Requirements table has the following fields:</para>
821
822 <itemizedlist spacing="compact">
823 <listitem>
824 <para>Disk size (mandatory). 2GB or more are required for
825 the installation.</para>
826 </listitem>
827
828 <listitem>
829 <para>CPU cores (mandatory). 2 cores or more are required
830 for the installation.</para>
831 </listitem>
832
833 <listitem>
834 <para>RAM (mandatory). 2GB or more are required for the
835 installation.</para>
836 </listitem>
837
838 <listitem>
839 <para>VT-x (mandatory). Intel Virtualization Technology must
840 be enabled.</para>
841 </listitem>
842
843 <listitem>
844 <para>VT-d (optional, recommended). Intel Virtualization
845 Technology for Directed I/O should be enabled.</para>
846 </listitem>
847
848 <listitem>
849 <para>IOMMU Group separation (optional). If the hardware
850 does not support IOMMU Group separation, there are certain
851 limitations regarding how the <literal>vfio-pci</literal>
852 driver can be used. For more details, see the <olink
853 targetdoc="book_enea_edge_release_info"
854 targetptr="bugs-limitations">Known Issues and Limitations in
855 this Release in the <xi:include
856 href="../../s_docbuild/olinkdb/pardoc-names.xml"
857 xmlns:xi="http://www.w3.org/2001/XInclude"
858 xpointer="element(book_enea_edge_release_info/1)" /></olink>
859 Manual.</para>
860 </listitem>
861 </itemizedlist>
862 </listitem>
863
864 <listitem>
865 <para>Force installation checkbox. When enabled, the
866 installation can be performed even if some of the mandatory
867 requirements are not met or if non-fatal problems are detected
868 during the process.</para>
869 </listitem>
870 </itemizedlist>
871 </listitem>
872
873 <listitem>
874 <para>On the Enea <emphasis role="bold">Edge Management
875 settings</emphasis> page of the Web-installer, the user must fill
876 in:</para>
877
878 <itemizedlist>
879 <listitem>
880 <para>The static Enea Edge Management IP Address or FQDN. This
881 can be either:</para>
882
883 <itemizedlist spacing="compact">
884 <listitem>
885 <para>The IP address of the Enea Edge Management host
886 machine, if the device can directly access it.</para>
887 </listitem>
888
889 <listitem>
890 <para>The IP address of the NAT device, if the Enea Edge
891 Management host is located behind a NAT. For more details,
892 please see <link linkend="firewall_config">Firewall
893 Configuration</link>.</para>
894 </listitem>
895
896 <listitem>
897 <para>The Fully Qualified Domain Name (FQDN) of the Enea
898 Edge Management host machine.</para>
899 </listitem>
900 </itemizedlist>
901 </listitem>
902
903 <listitem>
904 <para>The unique identifier of the uCPE device (called
905 "DeviceId" in this Manual).</para>
906 </listitem>
907
908 <listitem>
909 <para>Customer Tags. They are used for Zero Touch Provisioning
910 (ZTP) and can be left empty for a base configuration. What can
911 be entered here (if needed), are the tag(s) specified when
912 creating an offline configuration in the Enea Edge Management
913 application. A later addition of customer tags can only be done
914 by reinstalling the uCPE devices.</para>
915 </listitem>
916 </itemizedlist>
917 </listitem>
918
919 <listitem>
920 <para>Connect the WAN cable to the uCPE device (see Figure 2). This
921 will be used as the uCPE management network interface, as described
922 below.</para>
923 </listitem>
924
925 <listitem>
926 <para>On the <emphasis role="bold">Network Setup</emphasis> page of
927 the Web-installer, the user must do the following:</para>
928
929 <itemizedlist>
930 <listitem>
931 <para>Select a WAN interface to use as the management network
932 interface. This interface is used by the Enea Edge Management
933 application to communicate with the uCPE device.</para>
934 </listitem>
935
936 <listitem>
937 <para>Plug-in additional WAN interfaces (if applicable) and
938 provide their Layer 3 configuration.</para>
939 </listitem>
940 </itemizedlist>
941 </listitem>
942 </orderedlist>
943
944 <para>When the user has completed the configuration steps in the
945 Web-installer, Enea Edge Runtime is installed on the hard drive. At this
946 stage, the user should remove the USB stick and the LAN cable, and
947 shutdown the uCPE device. It will be started after necessary
948 configurations are done in the Enea Edge Management application, as
949 described below.</para>
950
951 <note>
952 <para>If errors are detected during installation, full logs will be
953 available on the last page of the Web-installer. Please contact Enea
954 for log analysis. The system is not expected to be usable if errors
955 are reported during installation.</para>
956
957 <para>If the USB stick was booted in UEFI mode, a UEFI boot entry is
958 automatically created and the system will start booting from the hard
959 drive without further user configuration.</para>
960 </note>
961 </section>
962
963 <section id="prep_phys_exec">
964 <title>Preparing Physical Deployment for Execution</title>
965
966 <figure>
967 <title>Preparing for Deployment Execution</title>
968
969 <mediaobject>
970 <imageobject>
971 <imagedata contentwidth="600" fileref="images/prep_execution.png" />
972 </imageobject>
973 </mediaobject>
974 </figure>
975
976 <para>The following network configuration is needed for managing the
977 uCPE device and service deployment:</para>
978
979 <itemizedlist>
980 <listitem>
981 <para>Network connection between the server running the Enea Edge
982 Management application and the laptop.</para>
983 </listitem>
984
985 <listitem>
986 <para>Network connection between the server running the Enea Edge
987 Management application and the uCPE device.</para>
988 </listitem>
989 </itemizedlist>
990 </section>
991 </section>
992
993 <section id="mg_ucpe_devices">
994 <title>Management of uCPE Devices</title>
995
996 <para>When the installation is complete the uCPE device can be managed in
997 the Enea Edge Management application.</para>
998
999 <section id="add_offline_config">
1000 <title>Add a default Offline Configuration</title>
1001
1002 <para>Zero Touch Provisioning is always turned on when a uCPE device
1003 connects to the Enea Edge Management application. To enable it in the
1004 Enea Edge Management application, an offline configuration needs to be
1005 registered for Day-0 configuration.</para>
1006
1007 <note>
1008 <para>Day-0 configuration is a software lifecycle term referring to
1009 early configurations used to put the uCPE device in an active state.
1010 Day-1 Configurations are applied after Day-0 and set the uCPE device
1011 and its service in an active state. Day-2 Configurations are live
1012 configurations on the uCPE device and its service, applied after they
1013 have been activated.</para>
1014 </note>
1015
1016 <para>The offline configuration consists of data and parameters that are
1017 meant to be automatically set when a uCPE device connects to the Enea
1018 Edge Management application for the first time. The configuration is
1019 typically focused on setting up the network management of the uCPE
1020 device, e.g. configuring network interfaces, WAN and LAN networking and
1021 service chains.</para>
1022
1023 <para>For this base configuration, the offline configuration will be
1024 left blank. The blank offline configuration can be filled with
1025 user-specific values and data once the service is created, which is done
1026 after the installation is complete.</para>
1027
1028 <note>
1029 <para>If the offline configuration is not configured, an alarm will be
1030 raised: <literal>Day-0 Config:ZTP:Major</literal> when the uCPE device
1031 tries to connect to the Enea Edge Management application, informing
1032 the user that the ZTP setup failed for the uCPE device.</para>
1033 </note>
1034
1035 <para><emphasis role="bold">Creating an offline
1036 configuration</emphasis></para>
1037
1038 <orderedlist>
1039 <listitem>
1040 <para>In a browser, access the Enea Edge Management application,
1041 open <emphasis role="bold">Applications</emphasis> and select
1042 <emphasis role="bold">Offline Config</emphasis>.</para>
1043 </listitem>
1044
1045 <listitem>
1046 <para>Create a new offline configuration in the GUI by selecting the
1047 <emphasis role="bold">Add</emphasis> button and filling in the
1048 mandatory fields: <literal>name</literal>,
1049 <literal>deviceVersion</literal> and
1050 <literal>deviceId</literal>.</para>
1051
1052 <para>The name is user defined and can be set to any unique text
1053 string identifying the configuration. The
1054 <literal>deviceVersion</literal> must match the Enea Edge Runtime
1055 version of the uCPE device and the <literal>deviceId</literal> must
1056 be the previously set identifier of the uCPE device
1057 (DeviceId).</para>
1058 </listitem>
1059 </orderedlist>
1060 </section>
1061
1062 <section id="add_ucpe_mg">
1063 <title>Add a uCPE device to the Management System</title>
1064
1065 <para>In order to enroll a uCPE device in the management system and
1066 establish a management connection, the user will add uCPE device
1067 information in the Enea Edge Management application. This is
1068 accomplished by going to <emphasis role="bold">Devices</emphasis>,
1069 selecting <emphasis role="bold">Manage</emphasis> and then clicking the
1070 <emphasis role="bold">Add</emphasis> button.</para>
1071
1072 <para>The relevant parameters are:</para>
1073
1074 <itemizedlist>
1075 <listitem>
1076 <para><emphasis role="bold">Type.</emphasis> The type of device to
1077 be added, i.e Enea universal CPE.</para>
1078 </listitem>
1079
1080 <listitem>
1081 <para><emphasis role="bold">Name.</emphasis> The name by which the
1082 uCPE device is referred to in the Enea Edge Management application.
1083 (Mandatory).</para>
1084 </listitem>
1085
1086 <listitem>
1087 <para><emphasis role="bold">SSH Port.</emphasis> The NETCONF Port
1088 used for communications. Default is set to 830.</para>
1089 </listitem>
1090
1091 <listitem>
1092 <para><emphasis role="bold">SSH User Name.</emphasis> The user name
1093 for SSH connectivity. Default user is root.</para>
1094 </listitem>
1095
1096 <listitem>
1097 <para><emphasis role="bold">SSH Password.</emphasis> Leave this
1098 blank.</para>
1099 </listitem>
1100
1101 <listitem>
1102 <para><emphasis role="bold">Device Calls Home.</emphasis> This
1103 checkbox indicates the direction of uCPE device communications. For
1104 a base configuration, leave this flag unchecked.</para>
1105 </listitem>
1106
1107 <listitem>
1108 <para><emphasis role="bold">Device ID.</emphasis> The unique
1109 identifier of the uCPE device. (Mandatory).</para>
1110 </listitem>
1111 </itemizedlist>
1112
1113 <para>For more details concerning Device Calls Home, please see <olink
1114 targetdoc="book_enea_edge_getting_started"
1115 targetptr="device_callhome_nat">Device Call Home Connection for
1116 Deployment behind NAT in the <xi:include
1117 href="../../s_docbuild/olinkdb/pardoc-names.xml"
1118 xmlns:xi="http://www.w3.org/2001/XInclude"
1119 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
1120 Manual.</para>
1121 </section>
1122
1123 <section id="boot_device_add_map">
1124 <title>Booting the uCPE device and adding it to the Map</title>
1125
1126 <para>When connectivity is established with the Enea Edge Management
1127 application and a uCPE device is already registered with a matching
1128 <literal>Device ID</literal>, the installation is complete, and the
1129 connection is established.</para>
1130
1131 <para>When a uCPE device is registered it can be manually added to the
1132 map for overview. <emphasis role="bold">Right-click</emphasis> on the
1133 map and select <emphasis role="bold">Place Device</emphasis> to put the
1134 uCPE device on the map.</para>
1135
1136 <para>In case of management connection failure (e.g. due to a
1137 misconfiguration), the uCPE device status will be seen as RED
1138 (disconnected) in the Enea Edge Management application. The uCPE device
1139 configuration can be corrected by removing the WAN cable(s),
1140 reconnecting the laptop to the LAN interface of the uCPE device and
1141 rebooting it. At this point, the Web-installer can be accessed from the
1142 laptop as described in <olink targetdoc="book_enea_edge_getting_started"
1143 targetptr="install_ena_device">Installing Enea Edge - uCPE Device
1144 installation in the <xi:include
1145 href="../../s_docbuild/olinkdb/pardoc-names.xml"
1146 xmlns:xi="http://www.w3.org/2001/XInclude"
1147 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
1148 Manual.</para>
1149 </section>
1150 </section>
1151
1152 <section id="ucpe_monitor">
1153 <title>uCPE Device Monitorization and Control</title>
1154
1155 <para>Once the uCPE device is connected to the Enea Edge Management
1156 application, it is ready for central management. Two important functions
1157 available in the Enea Edge Management GUI are alarm checking and resource
1158 allocation. Additionally, the device can be rebooted, the factory settings
1159 can be restored or simply the vCPE service can be restarted.</para>
1160
1161 <section id="check_alarms">
1162 <title>Checking Alarms</title>
1163
1164 <para>The Enea Edge Management application dashboard presents alarms in
1165 a specific window on the front page.</para>
1166
1167 <para>An alarm can be easily triggered by disconnecting and reconnecting
1168 the WAN ethernet cable from the uCPE device. The management system will
1169 detect the broken link and raise an alarm: <literal>Device
1170 Disconnected::Critical</literal>.</para>
1171
1172 <para>A separate Alarm Management window can be accessed from the Enea
1173 Edge Management menu for in-depth access and programming of <emphasis
1174 role="bold">Alarms and Events</emphasis>.</para>
1175 </section>
1176
1177 <section id="ck_resource_alloc">
1178 <title>Checking uCPE device Resource Allocation</title>
1179
1180 <para>When the uCPE device is connected to the Enea Edge Management
1181 application it is of interest to check the amount of hardware resources
1182 in use.</para>
1183
1184 <para>To check CPU, RAM and disk utilization simply select the uCPE
1185 device and go to the <emphasis role="bold">Virtual Machines</emphasis>
1186 tab in the map view. The same view will show active VNFs running on the
1187 uCPE device once instantiated.</para>
1188 </section>
1189
1190 <section id="basic_oper_device">
1191 <title>Basic operations for uCPE device Managememt</title>
1192
1193 <para>When the uCPE device is connected to the Enea Edge Management
1194 application, it can be rebooted, the factory settings can be restored or
1195 simply the vCPE service can be restarted.</para>
1196
1197 <para>Select the uCPE device and go to the <emphasis
1198 role="bold">Operations</emphasis> menu, where the following options are
1199 available:</para>
1200
1201 <itemizedlist>
1202 <listitem>
1203 <para><emphasis role="bold">Reboot</emphasis>. Reboots the device.
1204 Settings will be preserved.</para>
1205 </listitem>
1206
1207 <listitem>
1208 <para><emphasis role="bold">Factory reset</emphasis>. Resets the
1209 device to its default factory settings. All current configuration
1210 settings are lost. All running VNFs are destroyed. Any installed
1211 custom scripts will be removed and they will need to be
1212 reinstalled.</para>
1213
1214 <para>Only the vCPE service will be restarted, the device will not
1215 be rebooted. No reboot is needed.</para>
1216
1217 <para>Once the vCPE service restart completes, appropriate day-0
1218 provisioning will take place.</para>
1219 </listitem>
1220
1221 <listitem>
1222 <para><emphasis role="bold">Restart Vcpe</emphasis>. Restarts the
1223 vCPE service on the device. The device will not be rebooted.</para>
1224 </listitem>
1225 </itemizedlist>
1226 </section>
1227
1228 <section id="access_device_cli">
1229 <title>Accessing the uCPE device CLI</title>
1230
1231 <para>As a final check to make sure the uCPE device was installed and
1232 configured correctly, access the uCPE device Linux CLI by selecting the
1233 uCPE device on the map and using the <emphasis role="bold">SSH
1234 button</emphasis> from the panel. A new window will appear for CLI
1235 access. The default user and password are <literal>root</literal> and
1236 blank, respectively.</para>
1237
1238 <para>This is a pure Linux CLI providing access to standard Linux CLI
1239 commands. The CLI is a central feature for running custom
1240 scripting.</para>
1241
1242 <note>
1243 <para>In case the uCPE device was installed behind a NAT device, the
1244 reverse SSH connection will be used. For more details, please see
1245 <olink targetdoc="book_enea_edge_getting_started"
1246 targetptr="device_callhome_nat">Device Call Home Connection for
1247 deployment behind NAT in the <xi:include
1248 href="../../s_docbuild/olinkdb/pardoc-names.xml"
1249 xmlns:xi="http://www.w3.org/2001/XInclude"
1250 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
1251 Manual.</para>
1252 </note>
1253 </section>
1254 </section>
1255</chapter>
diff --git a/doc/book-enea-edge-getting-started/doc/introduction.xml b/doc/book-enea-edge-getting-started/doc/introduction.xml
new file mode 100644
index 0000000..eaa5521
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/introduction.xml
@@ -0,0 +1,269 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="intro_ucpe">
5 <title>Overview</title>
6
7 <para>This document describes Enea Edge and provides installation steps for
8 deploying a base configuration in order to create:</para>
9
10 <itemizedlist>
11 <listitem>
12 <para>A functional Enea Edge Management installation ready to manage
13 uCPE devices.</para>
14 </listitem>
15
16 <listitem>
17 <para>One or several managed uCPE devices, ready to host network
18 services, using one wired WAN and one wired LAN connection.</para>
19 </listitem>
20 </itemizedlist>
21
22 <para>Extended deployment and configuration options are also detailed in the
23 following chapters.</para>
24
25 <section id="ena_solution">
26 <title>Enea Edge</title>
27
28 <para>Enea Edge for universal Customer Premise Equipment (uCPE) is a
29 virtualization and management platform, which allows end-users to onboard,
30 instantiate, and run third-party VNFs onto their systems. It is comprised
31 of two major components working in close cooperation:</para>
32
33 <itemizedlist>
34 <listitem>
35 <para>Enea Edge Runtime, which acts as the host for Virtualized
36 Network Functions (VNFs) and provides management over NETCONF.</para>
37 </listitem>
38
39 <listitem>
40 <para>Enea Edge Management, an application that runs on an external
41 server, used for VNF Management and managing large numbers of uCPE
42 devices.</para>
43 </listitem>
44 </itemizedlist>
45
46 <para>In addition, Enea Edge includes a framework for automation and
47 testing. More information can be found in the <xi:include
48 href="../../s_docbuild/olinkdb/pardoc-common.xml"
49 xmlns:xi="http://www.w3.org/2001/XInclude"
50 xpointer="element(book_enea_edge_automation_user_guide/1)" />.</para>
51
52 <para>Details concerning release content, including documentation
53 structure, are provided in the <xi:include
54 href="../../s_docbuild/olinkdb/pardoc-common.xml"
55 xmlns:xi="http://www.w3.org/2001/XInclude"
56 xpointer="element(book_enea_edge_release_info/1)" /> Manual included
57 with your release.</para>
58
59 <section id="nfv_access">
60 <title>Enea Edge Runtime</title>
61
62 <para>Enea Edge Runtime is a lightweight, multi-architecture
63 virtualization platform built on de-facto standards in an SDN/NFV
64 ecosystem. It is designed for a high networking performance with minimal
65 hardware footprint, by only providing relevant functionalties and
66 technologies.</para>
67
68 <para>Virtualization methods include Virtual Machines (KVM / QEMU) and
69 container(s) (Docker). High networking throughput and low latency are
70 ensured by an accelerated data plane relying on technologies like DPDK,
71 OVS-DPDK and SR-IOV/PCI-Passthrough. Key functionalities, such as
72 platform software management, virtualized networking, VNFs life-cycle
73 management and FCAPS are provided through the YANG-modelled NETCONF
74 protocol.</para>
75
76 <figure>
77 <title>VNF Space</title>
78
79 <mediaobject>
80 <imageobject>
81 <imagedata align="center" contentwidth="600"
82 fileref="images/vnf_space.png" />
83 </imageobject>
84 </mediaobject>
85 </figure>
86 </section>
87
88 <section id="ucpe_manager">
89 <title>Enea Edge Management</title>
90
91 <para>The Enea Edge Management application is a centralized control system providing
92 domain management capabilities to uCPEs through a GUI and REST API. It can
93 be deployed on a host or a virtual machine running 64-bit CentOS 7 on an
94 x86 platform. The Enea Edge Management application uses a southbound NETCONF
95 protocol to connect and manage uCPE devices.</para>
96
97 <para>The Enea Edge Management application provides the following key
98 features:</para>
99
100 <itemizedlist>
101 <listitem>
102 <para>Enea Edge Runtime Software Management</para>
103 </listitem>
104
105 <listitem>
106 <para>VNF Onboarding</para>
107 </listitem>
108
109 <listitem>
110 <para>VNF Management</para>
111 </listitem>
112
113 <listitem>
114 <para>FCAPS</para>
115 </listitem>
116
117 <listitem>
118 <para>Zero Touch Provisioning</para>
119 </listitem>
120
121 <listitem>
122 <para>Alarms / Events management and monitoring</para>
123 </listitem>
124 </itemizedlist>
125 </section>
126 </section>
127
128 <section id="def_and_acr">
129 <title>Definitions and Acronyms</title>
130
131 <section id="definitions">
132 <title>Definitions</title>
133
134 <table>
135 <title>Definitions</title>
136
137 <tgroup cols="2">
138 <colspec align="left" colname="1" colwidth="1*" />
139
140 <colspec align="left" colname="2" colwidth="3*" />
141
142 <tbody>
143 <row>
144 <entry>Enea Edge</entry>
145
146 <entry>The Enea Edge Runtime and Enea Edge
147 Management solutions.</entry>
148 </row>
149
150 <row>
151 <entry>Enea Edge Runtime</entry>
152
153 <entry>A lightweight, multi-architecture virtualization
154 platform, supporting Virtual Machines.</entry>
155 </row>
156
157 <row>
158 <entry>Enea Edge Management</entry>
159
160 <entry>The Enea Universal Customer Premises Equipment
161 Manager.</entry>
162 </row>
163
164 <row>
165 <entry>uCPE device</entry>
166
167 <entry>A whitebox running the Enea Edge Runtime.</entry>
168 </row>
169 </tbody>
170 </tgroup>
171 </table>
172 </section>
173
174 <section id="acronyms">
175 <title>Acronyms</title>
176
177 <table>
178 <title>Acronyms</title>
179
180 <tgroup cols="2">
181 <colspec align="left" colname="1" colwidth="1*" />
182
183 <colspec align="left" colname="2" colwidth="3*" />
184
185 <tbody>
186 <row>
187 <entry>API</entry>
188
189 <entry>Application Programming Interface.</entry>
190 </row>
191
192 <row>
193 <entry>DPDK</entry>
194
195 <entry>Data Plane Development Kit.</entry>
196 </row>
197
198 <row>
199 <entry>EFI</entry>
200
201 <entry>Extensible Firmware Interface.</entry>
202 </row>
203
204 <row>
205 <entry>FCAPS</entry>
206
207 <entry>Fault-management, Configuration, Accounting, Performance
208 and Security.</entry>
209 </row>
210
211 <row>
212 <entry>NETCONF</entry>
213
214 <entry>Network Configuration Protocol.</entry>
215 </row>
216
217 <row>
218 <entry>NFV</entry>
219
220 <entry>Network Functions Virtualization.</entry>
221 </row>
222
223 <row>
224 <entry>OVS</entry>
225
226 <entry>Open vSwitch.</entry>
227 </row>
228
229 <row>
230 <entry>UEFI</entry>
231
232 <entry>Unified Extensible Firmware Interface.</entry>
233 </row>
234
235 <row>
236 <entry>SR-IOV</entry>
237
238 <entry>Single Root Input/Output Virtualization.</entry>
239 </row>
240
241 <row>
242 <entry>PCI</entry>
243
244 <entry>Peripheral Component Interconnect.</entry>
245 </row>
246
247 <row>
248 <entry>REST</entry>
249
250 <entry>Representational State Transfer.</entry>
251 </row>
252
253 <row>
254 <entry>VNF</entry>
255
256 <entry>Virtual Network Function.</entry>
257 </row>
258
259 <row>
260 <entry>vCPE</entry>
261
262 <entry>Virtual Customer Premises Equipment.</entry>
263 </row>
264 </tbody>
265 </tgroup>
266 </table>
267 </section>
268 </section>
269</chapter> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/doc/log_collector.xml b/doc/book-enea-edge-getting-started/doc/log_collector.xml
new file mode 100644
index 0000000..1148dc2
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/log_collector.xml
@@ -0,0 +1,418 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<chapter id="log_collector">
3 <title>Using the Log Collector</title>
4
5 <para>Troubleshooting problems on a uCPE device require an analysis of a set
6 of data and information i.e. logs collected from the uCPE device and/or the
7 Enea Edge Management application. The following information describes how
8 the log collection mechanism works.</para>
9
10 <section id="log_collect_ucpem">
11 <title>Log collecting using the Enea Edge Management application</title>
12
13 <para>The Enea Edge Management application allows for collecting a set of
14 logs and state information from a uCPE device.</para>
15
16 <section id="log_collect">
17 <title>Collecting the Logs</title>
18
19 <para>Collect the necessary log files and system details, then create an
20 archive (a tar file) on the uCPE device in the
21 <filename>/var/odm/log/archives</filename> folder:</para>
22
23 <orderedlist>
24 <listitem>
25 <para>Access <emphasis role="bold">Operations</emphasis> and then
26 select <emphasis role="bold">Collect Debug Logs</emphasis>.</para>
27 </listitem>
28
29 <listitem>
30 <para>Provide a file name in the new window.</para>
31 </listitem>
32
33 <listitem>
34 <para>Press the <emphasis role="bold">Execute</emphasis>
35 button.</para>
36
37 <para>A success message is shown in the same window as shown below.
38 At this moment, the process of collecting logs on the uCPE device
39 starts.</para>
40 </listitem>
41
42 <figure>
43 <title>Collecting Debug Logs</title>
44
45 <mediaobject>
46 <imageobject>
47 <imagedata align="center" contentwidth="500"
48 fileref="images/collect_debug_logs.png" />
49 </imageobject>
50 </mediaobject>
51 </figure>
52 </orderedlist>
53
54 <note>
55 <para>It might take some time for the archive to be created. When the
56 operation completes, a "CollectLogsComplete" notification is sent from
57 the uCPE device to the Enea Edge Management application. This can be
58 viewed in the GUI in the <emphasis role="bold">Faults</emphasis> menu,
59 after selecting <emphasis role="bold">Events</emphasis>.</para>
60
61 <figure>
62 <title>Collecting Debug Logs</title>
63
64 <mediaobject>
65 <imageobject>
66 <imagedata align="center" contentwidth="500"
67 fileref="images/fault_events.png" />
68 </imageobject>
69 </mediaobject>
70 </figure>
71 </note>
72 </section>
73
74 <section id="view_logs">
75 <title>View collected Logs</title>
76
77 <para>A list with the archives containing already collected logs will be
78 shown in the <emphasis role="bold">Device File Listing</emphasis>
79 table:</para>
80
81 <orderedlist>
82 <listitem>
83 <para>Access the <emphasis role="bold">Files</emphasis> menu and
84 select the <emphasis role="bold">Download</emphasis> button.</para>
85 </listitem>
86
87 <listitem>
88 <para>Press the <emphasis role="bold">List</emphasis> button.</para>
89
90 <figure>
91 <title>Device File Listing Table</title>
92
93 <mediaobject>
94 <imageobject>
95 <imagedata align="center" contentwidth="500"
96 fileref="images/archive_list.png" />
97 </imageobject>
98 </mediaobject>
99 </figure>
100 </listitem>
101 </orderedlist>
102
103 <note>
104 <para>If the filename you specified does not appear, it might still be
105 in the process of creation. Click on the <emphasis
106 role="bold">Refresh</emphasis> icon at the bottom of the table until
107 you can see the desired file listing.</para>
108 </note>
109 </section>
110
111 <section id="download_fr_dev">
112 <title>Downloading Logs from the uCPE Device</title>
113
114 <para>This option transfers a debug file archive from the uCPE device to
115 Enea Edge Management application.</para>
116
117 <orderedlist>
118 <listitem>
119 <para>Access the <emphasis role="bold">Files</emphasis> menu and
120 select the <emphasis role="bold">Download</emphasis> button.</para>
121 </listitem>
122
123 <listitem>
124 <para>Press the <emphasis role="bold">List</emphasis> button.</para>
125 </listitem>
126
127 <listitem>
128 <para>In the <emphasis role="bold">Device File Listing</emphasis>
129 table, select the archive you want to download from the uCPE device
130 to Enea Edge Management.</para>
131 </listitem>
132
133 <listitem>
134 <para>Press the <emphasis role="bold">Download from
135 Device</emphasis> button.</para>
136
137 <para>The archive will be downloaded from the uCPE device and stored
138 on the Enea Edge Management application.</para>
139 </listitem>
140 </orderedlist>
141
142 <note>
143 <para>The archive will not be deleted from the uCPE device after
144 download.</para>
145 </note>
146 </section>
147
148 <section id="download_logs_locally">
149 <title>Downloading collected Logs locally</title>
150
151 <para>This option downloads a logs archive from the Enea Edge Management
152 application to a local (user) machine for analysis. The archive must
153 first be available in the Enea Edge Management application in order to
154 be downloaded.</para>
155
156 <orderedlist>
157 <listitem>
158 <para>Access the <emphasis role="bold">Devices</emphasis> menu and
159 select <emphasis role="bold">Files</emphasis>.</para>
160 </listitem>
161
162 <listitem>
163 <para>Select the <emphasis role="bold">Downloaded Files</emphasis>
164 tab.</para>
165 </listitem>
166
167 <listitem>
168 <para>Select an archive from the <emphasis role="bold">Downloaded
169 Files</emphasis> table.</para>
170 </listitem>
171
172 <listitem>
173 <para>Click the <emphasis role="bold">Download</emphasis>
174 button.</para>
175
176 <para>The file will be downloaded in the download folder of the
177 supported browser in use.</para>
178
179 <figure>
180 <title>Downloaded Files Table</title>
181
182 <mediaobject>
183 <imageobject>
184 <imagedata align="center" contentwidth="500"
185 fileref="images/download_files.png" />
186 </imageobject>
187 </mediaobject>
188 </figure>
189 </listitem>
190 </orderedlist>
191 </section>
192
193 <section id="delete_log_archive_dev">
194 <title>Deleting a Logs Archive from a uCPE device</title>
195
196 <para>Use this option when you want to delete unnecessary collected logs
197 on a uCPE device.</para>
198
199 <orderedlist>
200 <listitem>
201 <para>Access the <emphasis role="bold">Files</emphasis> menu and
202 then click the <emphasis role="bold">Download</emphasis>
203 button.</para>
204 </listitem>
205
206 <listitem>
207 <para>Press the <emphasis role="bold">List</emphasis> button.</para>
208 </listitem>
209
210 <listitem>
211 <para>In the <emphasis role="bold">Device File Listing</emphasis>
212 table, select the archive you want to delete from the uCPE
213 device.</para>
214 </listitem>
215
216 <listitem>
217 <para>Press the <emphasis role="bold">Delete</emphasis>
218 button.</para>
219
220 <para>The archive will be deleted from the uCPE device and the table
221 will be updated.</para>
222 </listitem>
223 </orderedlist>
224
225 <para>The same can be achieved using these alternative options:</para>
226
227 <orderedlist>
228 <listitem>
229 <para>Access the <emphasis role="bold">Operations</emphasis> menu
230 and select <emphasis role="bold">Delete Debug Log
231 Archive</emphasis>.</para>
232 </listitem>
233
234 <listitem>
235 <para>Provide a file name in the new window.</para>
236 </listitem>
237
238 <listitem>
239 <para>Press the <emphasis role="bold">Execute</emphasis>
240 button.</para>
241
242 <para>A success message is displayed if the file is deleted from the
243 uCPE device correctly.</para>
244 </listitem>
245 </orderedlist>
246 </section>
247
248 <section id="delete_archives_ucpem">
249 <title>Deleting a Logs Archive from the Enea Edge Management
250 application</title>
251
252 <para>This option deletes a logs archive from the Enea Edge Management
253 application.</para>
254
255 <orderedlist>
256 <listitem>
257 <para>Access the <emphasis role="bold">Devices</emphasis> menu, then
258 select <emphasis role="bold">Files</emphasis>.</para>
259 </listitem>
260
261 <listitem>
262 <para>Select the <emphasis role="bold">Downloaded Files</emphasis>
263 tab.</para>
264 </listitem>
265
266 <listitem>
267 <para>Select an archive from the <emphasis role="bold">Downloaded
268 Files</emphasis> table.</para>
269 </listitem>
270
271 <listitem>
272 <para>Click the <emphasis role="bold">Delete</emphasis>
273 button.</para>
274
275 <para>The file will be deleted from the Enea Edge Management
276 application and the table will be updated.</para>
277 </listitem>
278 </orderedlist>
279
280 <note>
281 <para>Deleting the logs file from the Enea Edge Management application
282 does not affect the file located on the uCPE device.</para>
283 </note>
284 </section>
285
286 <section condition="hidden" id="enable_disable_via_perms">
287 <title>Enabling/Disabling the Log Collector via Permissions</title>
288
289 <para>To disable the ability to access/download the uCPE device's
290 debug-log files from the Enea Edge Management application, the
291 appropriate permissions must be changed:</para>
292
293 <orderedlist>
294 <listitem>
295 <para>Access the <emphasis role="bold">Security</emphasis> menu,
296 then select <emphasis role="bold">Configuration</emphasis>.</para>
297 </listitem>
298
299 <listitem>
300 <para>Click the <emphasis role="bold">Security Groups</emphasis>
301 tab.</para>
302 </listitem>
303
304 <listitem>
305 <para>Click the desired group.</para>
306 </listitem>
307
308 <listitem>
309 <para>Click the <emphasis role="bold">Permissions</emphasis> tab on
310 the right side.</para>
311 </listitem>
312
313 <listitem>
314 <para>Click the <emphasis role="bold">Devices</emphasis> tab like in
315 the image below.</para>
316 </listitem>
317
318 <listitem>
319 <para>Change the <emphasis role="bold">Device File
320 Management</emphasis> option to <emphasis
321 role="bold">none</emphasis> to disable the feature.</para>
322 </listitem>
323 </orderedlist>
324
325 <figure>
326 <title>Device File Management</title>
327
328 <mediaobject>
329 <imageobject>
330 <imagedata align="center" contentwidth="500"
331 fileref="images/dev_file_mg.png" />
332 </imageobject>
333 </mediaobject>
334 </figure>
335 </section>
336
337 <section id="download_ucpemg_logs">
338 <title>Downloading Enea Edge Management Logs</title>
339
340 <para>Often, sending the Enea Edge Management logs together with
341 collected uCPE device logs to the support team provides important
342 information for troubleshooting (especially in cases of connectivity
343 issues with the uCPE device and error popups).</para>
344
345 <para>Enea Edge Management log files are located in
346 <filename>application/logs/</filename> in the Enea Edge Management
347 application's installation folder
348 (e.g.<filename>/opt/ems/ucpemanager/application/logs</filename>). They
349 can be copied from that location, or they can be downloaded using the
350 Enea Edge Management GUI by performing the following:</para>
351
352 <orderedlist>
353 <listitem>
354 <para>Access <emphasis role="bold">Test</emphasis>, then <emphasis
355 role="bold">Debug Settings</emphasis> and select the <emphasis
356 role="bold">Log Files</emphasis> tab.</para>
357 </listitem>
358
359 <listitem>
360 <para>Select the desired log file
361 (<filename>ucpemanager.log</filename> or
362 <filename>watchdog.log</filename>) and press the <emphasis
363 role="bold">Download</emphasis> button.</para>
364 </listitem>
365
366 <listitem>
367 <para>A new (blank) popup window opens and the file is downloaded
368 locally. This popup can be closed after the download.</para>
369 </listitem>
370
371 <listitem>
372 <para>Repeat steps 2. And 3. Until all the desired log files have
373 been downloaded</para>
374 </listitem>
375 </orderedlist>
376
377 <figure>
378 <title>Debug Settings</title>
379
380 <mediaobject>
381 <imageobject>
382 <imagedata align="center" contentwidth="500"
383 fileref="images/debug_settings.png" />
384 </imageobject>
385 </mediaobject>
386 </figure>
387 </section>
388 </section>
389
390 <section id="log_collect_no_ucpem">
391 <title>Log collecting without using the Enea Edge Management
392 application</title>
393
394 <para>Log collection from uCPE Devices can also be done when there is no
395 Enea Edge Management connection. A SSH connection to the uCPE Device is
396 needed for use of the log collector script, which can be found in the uCPE
397 Device file system in <literal>/usr/local/enea/</literal>.</para>
398
399 <para>The Log collector script takes relevant information about the system
400 and collects it in an archive:</para>
401
402 <programlisting>./log-collector.sh -p &lt;LOG_PATHh&gt; -n &lt;ARCHIVE_NAME&gt;</programlisting>
403
404 <para>Where <literal>-p</literal> is the path where the log archive will
405 be saved, and <literal>-n</literal> is the archive name.</para>
406
407 <note>
408 <para>If <literal>-p</literal> is not provided, the default path will be
409 used: <literal>/var/logcollector</literal>. If <literal>-n</literal> is
410 not provided, the default name will be used:
411 <filename>log_archive_&lt;timestamp&gt;.tar.gz</filename>.</para>
412 </note>
413
414 <para>To access the help menu of the script:</para>
415
416 <programlisting>./log-collector.sh -h</programlisting>
417 </section>
418</chapter> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/doc/net_config_options.xml b/doc/book-enea-edge-getting-started/doc/net_config_options.xml
new file mode 100644
index 0000000..ff513c9
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/net_config_options.xml
@@ -0,0 +1,913 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<chapter id="net_config_operations">
3 <title>Network Configuration Options</title>
4
5 <para>Various Advanced Network Configuration options can be done from the
6 Enea Edge Management application GUI.</para>
7
8 <section id="device_callhome_nat">
9 <title>Device Call Home Connection for Deployment behind NAT</title>
10
11 <para>The Device Call Home option enables the initiation of the connection
12 between the uCPE Device and the Enea Edge Management application, from the
13 uCPE device. The Device Call Home option is required when deploying a uCPE
14 device behind NAT since the IP address of the uCPE device is hidden for
15 the Enea Edge Management application.</para>
16
17 <para>Enable Device Call Home by marking the Device Call Home checkbox
18 when registering the uCPE device in Enea Edge Management application. When
19 using this mechanism, the device will initiate a connection to the Enea
20 Edge Management application for NETCONF traffic (over SSH), while the
21 application waits for a device connection.</para>
22 </section>
23
24 <section id="device_net_config">
25 <title>uCPE Device Network Configuration</title>
26
27 <para>The following describes the steps required for setting up the
28 virtualization infrastructure, ensuring that a uCPE device has networking
29 setup for virtualized service deployment. Networking is enabled by
30 selecting physical interfaces to be used by virtualized networking and
31 creating different types of bridges to enable VNF communication.</para>
32
33 <para>The Zero Touch Provisioning mechanism is also touched upon, as an
34 alternative to manual configuration of the virtualization
35 infrastructure.</para>
36
37 <section id="config_dpdk">
38 <title>Configure DPDK</title>
39
40 <para>DPDK is an important functionality for accelerating networking
41 performance. The DPDK is enabled by default and should be utilized in
42 most configurations.</para>
43
44 <para>In use cases where CPU capacity is very limited, disabling DPDK
45 can free up CPU capacity and overall performance can improve. Navigate
46 to <emphasis role="bold">Configuration</emphasis>, then <emphasis
47 role="bold">DPDK</emphasis> and deselect <emphasis role="bold">Enable
48 DPDK</emphasis> to disable the DPDK.</para>
49
50 <note>
51 <para>Disabling the DPDK cannot be done after other network
52 configurations have been made.</para>
53 </note>
54
55 <para>In the <emphasis role="bold">Configuration</emphasis> menu, select
56 <emphasis role="bold">DPDK</emphasis>, here DPDK resources can also be
57 configured:</para>
58
59 <itemizedlist>
60 <listitem>
61 <para><emphasis role="bold">LCore Mask</emphasis>. Allocated cores
62 for non-datapath OVS-DPDK threads (CPU core bitmask). Default:
63 0x2.</para>
64 </listitem>
65
66 <listitem>
67 <para><emphasis role="bold">PMD CPU Mask</emphasis>. Allocated cores
68 for datapath processing (CPU core bitmask). Default: 0x4.</para>
69 </listitem>
70
71 <listitem>
72 <para><emphasis role="bold">Socket Memory</emphasis>. Hugepage
73 memory allocated for DPDK. Default: 1494.</para>
74 </listitem>
75 </itemizedlist>
76 </section>
77
78 <section id="config_ext_interfaces">
79 <title>Configure External Interfaces</title>
80
81 <para>Once a management connection with the uCPE device has been
82 established by using any of the supported methods, the virtualization
83 networking infrastructure can be configured either manually or by using
84 Zero Touch Provisioning.</para>
85
86 <para>Available network interfaces can be added to the management
87 system, for use by the networking virtualization infrastructure.</para>
88
89 <para>In order to make physical network interfaces available to the
90 virtualization infrastructure and VNFs, they must be configured into the
91 management system.</para>
92
93 <para>To add an interface into the Enea Edge Management application,
94 select the uCPE device, then from the top toolbar select <emphasis
95 role="bold">Configuration</emphasis>, then <emphasis
96 role="bold">External Interfaces</emphasis>, <emphasis
97 role="bold">Configuration</emphasis>, and click the <emphasis
98 role="bold">Add</emphasis> button. The available Interface types are
99 detailed below.</para>
100
101 <section id="dpdk_interface_type">
102 <title>DPDK Interface Type</title>
103
104 <para>Configuring a physical interface in DPDK mode will require a
105 DPDK-based application (e.g. OVS-DPDK) in order to access and use the
106 interface. An interface set as DPDK can be attached to an OVS-DPDK
107 bridge.</para>
108
109 <note>
110 <para>Make sure the <emphasis role="bold">Enable DPDK</emphasis>
111 checkbox is selected by accessing <emphasis
112 role="bold">Device</emphasis>, <emphasis
113 role="bold">Configuration</emphasis> and choosing <emphasis
114 role="bold">DPDK</emphasis>, otherwise no interface can be assigned
115 as DPDK.</para>
116 </note>
117
118 <para>To add a DPDK interface under the management system, set
119 appropriate values for the following fields:</para>
120
121 <itemizedlist>
122 <listitem>
123 <para>Source: name of the physical interface.</para>
124 </listitem>
125
126 <listitem>
127 <para>Networking-type: dpdk</para>
128 </listitem>
129
130 <listitem>
131 <para>Dpdk-type: the kernel module that allows user space access
132 to the physical interface. Either the <literal>vfio-pci</literal>
133 (most commonly used type) or the <literal>igb_uio</literal> driver
134 can be used.</para>
135 </listitem>
136 </itemizedlist>
137 </section>
138
139 <section id="sriov_interface_type">
140 <title>SR-IOV Interface Type</title>
141
142 <para>SR-IOV technology allows for the creation of a number of virtual
143 functions on the host interface, which can be used by VNFs running on
144 the uCPE device.</para>
145
146 <para>For SR-IOV mode configuration, the user must set values for the
147 following fields:</para>
148
149 <itemizedlist>
150 <listitem>
151 <para>Source: name of the physical interface.</para>
152 </listitem>
153
154 <listitem>
155 <para>Networking-type: srIov</para>
156 </listitem>
157
158 <listitem>
159 <para>sriov-mode: adapter-pool</para>
160 </listitem>
161
162 <listitem>
163 <para>sriov-num-vfs: the number of virtual functions to
164 create.</para>
165 </listitem>
166 </itemizedlist>
167 </section>
168
169 <section id="standard_interface_type">
170 <title>Standard Interface Type</title>
171
172 <para>Some of the physical network interfaces available on a uCPE
173 device, including Ethernet interfaces, do not have DPDK or SR-IOV
174 support. Instead, the Linux kernel driver has to be used.</para>
175
176 <para>To add Standard Interfaces under the management system, the user
177 must set values for the following fields:</para>
178
179 <itemizedlist>
180 <listitem>
181 <para>Source: the name of physical interface.</para>
182 </listitem>
183
184 <listitem>
185 <para>Networking-type: standard.</para>
186 </listitem>
187 </itemizedlist>
188 </section>
189
190 <section id="wan_interface_type">
191 <title>Wan Interface Type</title>
192
193 <para>WAN interfaces configured during the installation of the uCPE
194 device are automatically added in the Enea Edge Management application
195 as type <literal>wan</literal>. The WAN interface used for management
196 of the uCPE device is marked with the <literal>Management</literal>
197 property set to <literal>True</literal>.</para>
198
199 <para>If a WAN interface is to be assigned for use by a VNF, it must
200 be changed into another interface type depending on the type of
201 connection that will be used. The management WAN interface cannot be
202 changed to a different type. It is automatically used when an In-band
203 management bridge is created.</para>
204
205 <para><emphasis role="bold">How to Edit the Configuration of a Wan
206 Interface</emphasis></para>
207
208 <orderedlist>
209 <listitem>
210 <para>To edit an interface configuration type from the Enea Edge
211 Management, select the uCPE device, then from the top toolbar
212 select the <emphasis role="bold">Configuration</emphasis> menu,
213 then <emphasis role="bold">External Interfaces</emphasis> and
214 <emphasis role="bold">Configuration</emphasis>. The already
215 configured interfaces are displayed here, as seen in the figure
216 above.</para>
217 </listitem>
218
219 <listitem>
220 <para>In order to edit an already configured interface, (as in the
221 example popup shown below, a WAN interface) double click on the
222 desired one and a popup will appear. A different popup appears for
223 each type of interface. From the <emphasis role="bold">Host
224 Interface</emphasis> window, a user can change the networking type
225 and the IP address assignment:</para>
226
227 <figure>
228 <title>Editing an Interface</title>
229
230 <mediaobject>
231 <imageobject>
232 <imagedata align="center" contentwidth="450"
233 fileref="images/edit_inter.png" />
234 </imageobject>
235 </mediaobject>
236 </figure>
237 </listitem>
238 </orderedlist>
239
240 <note>
241 <para>When changing the <literal>address-assignment</literal> from
242 static to DHCP, if any of the <literal>ip-address</literal>,
243 <literal>netmask</literal> or <literal>gateway</literal> fields have
244 invalid values a validation error will be triggered. These fields
245 must be empty or have the valid values for their respective address
246 assignment.</para>
247 </note>
248 </section>
249
250 <section id="wap_interface_type">
251 <title>Wap Interface Type</title>
252
253 <para>Wireless Access Point (Wap) interfaces are used to create
254 Wireless Access Points. Only interfaces with
255 <literal>wap-capable</literal> capabilities can be added as WAP
256 interfaces.</para>
257
258 <para><emphasis role="bold">How to edit the Configuration of a Wap
259 Interface</emphasis></para>
260
261 <orderedlist>
262 <listitem>
263 <para>To edit an interface configuration from the Enea Edge
264 Management, select the uCPE device, then from the top toolbar
265 select the <emphasis role="bold">Configuration</emphasis> menu
266 then <emphasis role="bold">External Interfaces</emphasis> and
267 select <emphasis role="bold">Configuration</emphasis>. The already
268 configured interfaces will be displayed here.</para>
269 </listitem>
270
271 <listitem>
272 <para>In order to edit an already configured interface, (as in the
273 example popup shown below, a WAP interface) double click on the
274 desired one and a pop-up will appear. A different pop-up appears
275 for each type of interface. From the <literal>Host
276 Interface</literal> window, the following parameters are
277 configurable:</para>
278
279 <itemizedlist>
280 <listitem>
281 <para>Country Code: the country code, a 2 letter
282 ISO3166-alpha2 identifier.</para>
283 </listitem>
284
285 <listitem>
286 <para>Wireless Band: 2.4 GHz or 5 GHz. Depending on the band
287 selection, the correct <literal>Wireless Mode</literal> and
288 <literal>Radio Channel</literal> must be provided.</para>
289 </listitem>
290 </itemizedlist>
291
292 <figure>
293 <title>Editing an Interface</title>
294
295 <mediaobject>
296 <imageobject>
297 <imagedata align="center" contentwidth="475"
298 fileref="images/wap_external_interface.png" />
299 </imageobject>
300 </mediaobject>
301 </figure>
302 </listitem>
303 </orderedlist>
304
305 <note>
306 <para>Correct <emphasis role="bold">Country Code</emphasis>
307 selection is mandatory. All configuration options are available in
308 the Enea Edge Management application GUI but only the Radio Settings
309 that conform with the selected country's official regulatory laws
310 will be applied when the Wireless AP is started on the uCPE
311 Device.</para>
312 </note>
313 </section>
314
315 <section id="man_configuration">
316 <title>Manual Configuration</title>
317
318 <para>For Manual Configuration of uCPE networking, select the uCPE
319 device first, then access the <emphasis
320 role="bold">Configuration</emphasis> menu, and choose <emphasis
321 role="bold">External Interfaces</emphasis>, where a list of available
322 network interfaces and their capabilities can be found.</para>
323
324 <para>After networking interfaces have been added to the Enea Edge
325 Management, the user can change the interface type (DPDK, SR-IOV,
326 Standard, WAN, WAP).</para>
327
328 <figure>
329 <title>Configuration of External Interfaces</title>
330
331 <mediaobject>
332 <imageobject>
333 <imagedata align="center" contentwidth="600"
334 fileref="images/edit_inter_config.png" />
335 </imageobject>
336 </mediaobject>
337 </figure>
338 </section>
339 </section>
340
341 <section id="configure_bridges">
342 <title>Configuring Bridges</title>
343
344 <para>After networking interfaces have been added to the Enea Edge
345 Management, the user can create the necessary OVS bridges.</para>
346
347 <figure>
348 <title>OVS Bridges</title>
349
350 <mediaobject>
351 <imageobject>
352 <imagedata align="center" contentwidth="600"
353 fileref="images/ovs_bridges_tab.png" />
354 </imageobject>
355 </mediaobject>
356 </figure>
357
358 <para><emphasis role="bold">How to add OVS bridges in the Enea Edge
359 Management</emphasis></para>
360
361 <orderedlist>
362 <listitem>
363 <para>Select the uCPE device.</para>
364 </listitem>
365
366 <listitem>
367 <para>Select <emphasis role="bold">Configuration</emphasis>.</para>
368 </listitem>
369
370 <listitem>
371 <para>Click <emphasis role="bold">OpenvSwitch</emphasis>.</para>
372 </listitem>
373
374 <listitem>
375 <para>Select the <emphasis role="bold">Bridges</emphasis> option,
376 then click <emphasis role="bold">Add</emphasis>.</para>
377 </listitem>
378 </orderedlist>
379
380 <note>
381 <para>Depending on the settings found when accessing the <emphasis
382 role="bold">Configuration</emphasis> menu and selecting <emphasis
383 role="bold">DPDK</emphasis>, OVS bridges with or without DPDK support
384 will be used on the uCPE device.</para>
385 </note>
386
387 <para>There are three types of bridges which can be created, each one
388 fulfiling a different role.</para>
389
390 <section id="inband_mg_bridge">
391 <title>uCPE In-band Management bridge</title>
392
393 <para>In-band Management refers to a model where both the data plane
394 and control plane flow over the same network path. In some situations
395 (e.g. the uCPE device has only one routable IP address), this is the
396 only option available to both control and configure the uCPE device,
397 while also allowing for data-path traffic to pass over the same
398 physical interface.</para>
399
400 <para>The solution provided by Enea for in-band management is based
401 upon an OpenvSwitch bridge managing all traffic passing through the
402 WAN physical port. Any standard or DPDK-assigned network interface can
403 be used for the In-Band management bridge.</para>
404
405 <para>To create the In-Band Management bridge, the user must set
406 values for the following fields:</para>
407
408 <itemizedlist>
409 <listitem>
410 <para>name: name of the bridge.</para>
411 </listitem>
412
413 <listitem>
414 <para>ovs-bridge-type: inbandMgmt</para>
415 </listitem>
416 </itemizedlist>
417 </section>
418
419 <section id="inband_mg_br_vnfs">
420 <title>In-band Management bridge for VNFs</title>
421
422 <para>If VNF management can be done over a dedicated virtual
423 interface, its possible to extend the networking infrastructure
424 configuration to also access the VNF's management interface over the
425 WAN port.</para>
426
427 <para>For this setup, three types of traffic will pass over the WAN
428 physical interface:</para>
429
430 <itemizedlist>
431 <listitem>
432 <para><emphasis role="bold">Device management</emphasis>. Part of
433 the device configuration done by the Enea Edge Management
434 application.</para>
435 </listitem>
436
437 <listitem>
438 <para><emphasis role="bold">VNF(s) management</emphasis>. Enabling
439 or disabling features of a VNF. E.g. enabling/disabling the
440 firewall or VPN setup.</para>
441 </listitem>
442
443 <listitem>
444 <para><emphasis role="bold">Data-path</emphasis>. All other
445 traffic that is not used in the control plane and needs to reach a
446 LAN network.</para>
447 </listitem>
448 </itemizedlist>
449
450 <para>To create a VNF In-Band Management bridge, the user must set
451 values for the following fields:</para>
452
453 <itemizedlist>
454 <listitem>
455 <para>name: name of the bridge.</para>
456 </listitem>
457
458 <listitem>
459 <para>ovs-bridge-type: vnfMgmt</para>
460 </listitem>
461
462 <listitem>
463 <para>vnf-mgmt-address: select IPv4 as the type and fill in an
464 internal IP address for the bridge interface that will be
465 connected to the VNF management network, e.g 10.0.0.1.</para>
466 </listitem>
467 </itemizedlist>
468
469 <note>
470 <para>VNF management interfaces must be configured in same subnet as
471 that used by the bridge interface connected to the VNF management
472 network.</para>
473 </note>
474 </section>
475
476 <section id="dataplane_bridge">
477 <title>Data-plane bridge</title>
478
479 <para>Data-plane bridges are generic bridges used for the VNF
480 data-plane. There are two supported sub-types:</para>
481
482 <itemizedlist>
483 <listitem>
484 <para><emphasis role="bold">communication</emphasis>:
485 <itemizedlist>
486 <listitem>
487 <para>Allows for VNF communication towards LAN/WAN networks.
488 This bridge type has at least one physical port attached to
489 it.</para>
490 </listitem>
491
492 <listitem>
493 <para>Allows for creation of <literal>Wireless Access
494 Points</literal>. This bridge type does not need a physical
495 port attached to it.</para>
496 </listitem>
497 </itemizedlist></para>
498 </listitem>
499
500 <listitem>
501 <para><emphasis role="bold">integration</emphasis>: allows for
502 VNF-to-VNF communication (usually for service function chaining).
503 This bridge type does not have any physical port attached.</para>
504 </listitem>
505 </itemizedlist>
506
507 <para>To create a Data-plane bridge, the user must set values for the
508 following fields:</para>
509
510 <itemizedlist>
511 <listitem>
512 <para><emphasis role="bold">name</emphasis>: name of the
513 bridge.</para>
514 </listitem>
515
516 <listitem>
517 <para><emphasis role="bold">ovs-bridge-type</emphasis>: select
518 <literal>communication</literal> or
519 <literal>integration</literal>, depending on intended usage. For
520 communication bridges, physical interfaces can be added to the
521 bridge.</para>
522 </listitem>
523 </itemizedlist>
524 </section>
525 </section>
526 </section>
527
528 <section id="zero_touch_prov">
529 <title>Zero Touch Provisioning - Creating an Offline Configuration</title>
530
531 <para>Zero-Touch Provisioning (ZTP) refers to the process of when a device
532 starts up for the first time and its initial configuration is pushed down
533 by an external management system, so that it is setup for proper operation
534 without additional manual intervention by an operator. ZTP is an
535 alternative to Manual configuration.</para>
536
537 <para>A variety of operations can occur as part of ZTP such as initial
538 device setup, configuration of managed objects, etc. The goal is to set up
539 a device to the maximum possible extent without forcing an operator to be
540 physically present (initially) to manage the device.</para>
541
542 <para>An offline configuration is usually prepared in advance for the Enea
543 Edge Management to setup the virtualization infrastructure on the uCPE
544 device, as soon as a device enrolls into the management system.</para>
545
546 <section id="offline_configuration">
547 <title>Offline Configuration</title>
548
549 <para>The Offline Configuration subsystem is used to pre-populate a
550 configuration for a device that will be brought under management at a
551 future point in time. When creating an offline configuration store a
552 <literal>Device ID</literal> can be specified. This ID uniquely
553 identifies the device to be initialized.</para>
554
555 <para>Alternatively, a wildcard can be used in the <literal>Device
556 ID</literal> field, which results in a configuration being pushed on all
557 uCPE devices upon their initial connection towards the Enea Edge
558 Management.</para>
559
560 <para>If the offline configuration is not configured for a uCPE device,
561 an alarm will be raised: <literal>Day-0 Config:ZTP:Major</literal>,
562 which occurs when the uCPE device connects to the Enea Edge Management
563 application informing that the ZTP setup failed for the specific uCPE
564 device.</para>
565
566 <para>To create an offline configuration, select from the top toolbar
567 the <emphasis role="bold">Applications</emphasis> menu, then <emphasis
568 role="bold">Offline Config</emphasis> and choose <emphasis
569 role="bold">Add</emphasis>. The following fields should be
570 filled:</para>
571
572 <itemizedlist>
573 <listitem>
574 <para>Name: name of the device.</para>
575 </listitem>
576
577 <listitem>
578 <para>Device type: Enea universal CPE.</para>
579 </listitem>
580
581 <listitem>
582 <para>DeviceVersion: <xi:include
583 href="../../s_doceneacommon/doc/eltf_params_updated.xml"
584 xmlns:xi="http://www.w3.org/2001/XInclude"
585 xpointer="element(EneaLinux_REL_VER/1)" /></para>
586 </listitem>
587
588 <listitem>
589 <para>Config Set: uCPE Config</para>
590 </listitem>
591
592 <listitem>
593 <para>Device ID: device ID or a wildcard(*).</para>
594 </listitem>
595
596 <listitem>
597 <para>Device Grouping Tags: a tag to group devices. These tags match
598 the customer tags provided during the installation of the
599 device.</para>
600 </listitem>
601 </itemizedlist>
602
603 <para>The Name is user defined and can be set to any unique text string
604 identifying the configuration. The Device Version will match the Enea
605 Edge version of the uCPE device and the Device ID will be set to the
606 previously set identifier of the uCPE device.</para>
607
608 <para>When a device connects to the Enea Edge Management application for
609 the first time, it checks the device to see if it has been Zero Touch
610 Provisioned (ZTP). If not, it looks for an offline configuration that
611 matches these values, in the following order:</para>
612
613 <itemizedlist>
614 <listitem>
615 <para>The Device ID.</para>
616 </listitem>
617
618 <listitem>
619 <para>The set of tags.</para>
620 </listitem>
621
622 <listitem>
623 <para>A "*" for Device ID (wildcard).</para>
624 </listitem>
625 </itemizedlist>
626
627 <para>If a match is found, the offline configuration is sent to the
628 device as part of Zero-Touch-Provisioning.</para>
629
630 <para>After creating the Offline Config Store, access the device by
631 selecting <emphasis role="bold">Applications</emphasis>, then <emphasis
632 role="bold">offline config</emphasis> and clicking <emphasis
633 role="bold">Config App</emphasis>, to provision it with the required
634 initial configuration. This operation mirrors what happens during manual
635 configuration described previously.</para>
636
637 <note>
638 <para>The ZTP will only be triggered the first time a uCPE device
639 connects to the Enea Edge Management application. Just changing an
640 offline configuration will not push the new changes to the device. If
641 an offline configuration is changed after uCPE device registration, a
642 factory reset can be executed to force a new ZTP to execute. Select
643 the device, then access the <emphasis
644 role="bold">Operations</emphasis> menu and select <emphasis
645 role="bold">factory reset</emphasis>.</para>
646 </note>
647 </section>
648 </section>
649
650 <section id="custom_scripts">
651 <title>Custom Scripts for Custom Networking Configurations</title>
652
653 <para>The custom scripts feature allows users to execute user-defined
654 scripts on the uCPE device at various times.This allows for more flexible
655 and advanced configurations such as a LTE modem configuration, advanced
656 network configurations or OVS flow rule programming at any time.</para>
657
658 <section id="upload_scripts">
659 <title>Uploading Scripts</title>
660
661 <para>The scripts need to be uploaded to the Enea Edge Management
662 application prior to use. When uploading scripts to the Enea Edge
663 Management application make sure to select the right script type.</para>
664
665 <para>The following script types are supported:</para>
666
667 <itemizedlist>
668 <listitem>
669 <para><literal>Once-before-startup</literal>. This script will only
670 execute once after the system has rebooted, prior to processing any
671 device configuration.</para>
672 </listitem>
673
674 <listitem>
675 <para><literal>Always-before-startup</literal>. This script will
676 always execute after the system has rebooted, prior to processing
677 any device configuration.</para>
678 </listitem>
679
680 <listitem>
681 <para><literal>Once-after-startup</literal>. The script will always
682 execute after the system has rebooted, after all device
683 configuration processes have completed.</para>
684 </listitem>
685
686 <listitem>
687 <para><literal>Always-after-startup</literal>. This script will
688 always execute after all device configuration processes have
689 completed after the system has rebooted.</para>
690 </listitem>
691 </itemizedlist>
692
693 <note>
694 <para>After a factory reset, any of the
695 <literal>Once-before-*</literal> or <literal>Once-after-*</literal>
696 scripts will be re-run as described above.</para>
697 </note>
698
699 <para>Follow the instruction below to upload scripts:</para>
700
701 <orderedlist>
702 <listitem>
703 <para>Access the <emphasis role="bold">Devices</emphasis> menu, then
704 <emphasis role="bold">Custom Scripts</emphasis> and choose <emphasis
705 role="bold">Configure</emphasis>.</para>
706 </listitem>
707
708 <listitem>
709 <para>Select <emphasis role="bold">Upload to EMS</emphasis>.</para>
710 </listitem>
711
712 <listitem>
713 <para>In the <emphasis role="bold">Script Type</emphasis> menu,
714 select the type the uploaded script should have.</para>
715 </listitem>
716
717 <listitem>
718 <para>Press <emphasis role="bold">Choose File</emphasis> to select
719 the scripts needed, and then click <emphasis
720 role="bold">Send</emphasis>.</para>
721 </listitem>
722 </orderedlist>
723 </section>
724
725 <section id="remove_scripts">
726 <title>Removing Scripts</title>
727
728 <para>Follow the instruction below to remove scripts from the Enea Edge
729 Management application:</para>
730
731 <orderedlist>
732 <listitem>
733 <para>Access the <emphasis role="bold">Devices</emphasis> menu, then
734 <emphasis role="bold">Custom Scripts</emphasis> and select <emphasis
735 role="bold">Configure</emphasis>.</para>
736 </listitem>
737
738 <listitem>
739 <para>Select the script you want to delete from the <emphasis
740 role="bold">Uploaded Scripts</emphasis> tab and then click <emphasis
741 role="bold">Delete</emphasis>, which will remove the script
742 immediately from the Enea Edge Management application.</para>
743 </listitem>
744 </orderedlist>
745 </section>
746
747 <section id="configure_scripts">
748 <title>Configuring Script Location</title>
749
750 <para>The location where the scripts are staged in the Enea Edge
751 Management application can be changed as described below:</para>
752
753 <orderedlist>
754 <listitem>
755 <para>Access the <emphasis role="bold">Devices</emphasis> menu,
756 choose <emphasis role="bold">Custom Scripts</emphasis> and select
757 <emphasis role="bold">Configure</emphasis>.</para>
758 </listitem>
759
760 <listitem>
761 <para>Select the <emphasis role="bold">Configuration</emphasis> tab
762 and specify a new location to store the scripts.</para>
763
764 <note>
765 <para>Change the script storage location only if you have many
766 scripts which you would prefer to store on another partition,
767 otherwise leave this configuration as is.</para>
768 </note>
769 </listitem>
770 </orderedlist>
771 </section>
772
773 <section id="run_the_scripts">
774 <title>Running the Scripts</title>
775
776 <para><emphasis role="bold">How to run Custom Scripts</emphasis></para>
777
778 <orderedlist>
779 <listitem>
780 <para>Access the <emphasis role="bold">Devices</emphasis> menu,
781 choose <emphasis role="bold">Custom Scripts</emphasis> and select
782 <emphasis role="bold">Apply Scripts</emphasis>.</para>
783 </listitem>
784
785 <listitem>
786 <para>In the <emphasis role="bold">Script Config Screen</emphasis>
787 pop up, select the devices from the device(s) chooser list on which
788 to run the scripts. Press the <emphasis role="bold">&gt;</emphasis>
789 button to move the devices to the right side of the chooser, which
790 is the list of devices that will execute the selected
791 scripts.</para>
792 </listitem>
793
794 <listitem>
795 <para>Select the scripts from the list under the device(s) chooser
796 by pressing the <emphasis role="bold">+</emphasis> button.</para>
797 </listitem>
798
799 <listitem>
800 <para>In the pop-up window, select the scripts from the list. If
801 there are no scripts to select, then there is no script uploaded
802 with that particular type. Upload the script(s) needed and try
803 again.</para>
804 </listitem>
805
806 <listitem>
807 <para>Check the <emphasis role="bold">Reboot devices</emphasis>
808 checkbox if you want to reboot and execute the scripts at once and
809 then select <emphasis role="bold">ok</emphasis>.</para>
810
811 <note>
812 <para>The status of execution for the scripts can be seen by
813 accessing <emphasis role="bold">Fault</emphasis>, opening the
814 <emphasis role="bold">Events</emphasis> screen and filtering by
815 device and/or the event name
816 <filename>CustomScriptExecuted</filename>.</para>
817 </note>
818 </listitem>
819 </orderedlist>
820 </section>
821
822 <section id="remove_script_device">
823 <title>Removing Scripts from a uCPE Device</title>
824
825 <para>Follow the instructions below to remove scripts from a uCPE
826 Device:</para>
827
828 <orderedlist>
829 <listitem>
830 <para>Access the <emphasis role="bold">Operations</emphasis> menu
831 and select <emphasis role="bold">Delete Custom
832 Script</emphasis>.</para>
833 </listitem>
834
835 <listitem>
836 <para>In the <emphasis role="bold">Delete Custom Script</emphasis>
837 pop up, set the name and the type of the script that should be
838 deleted and press <emphasis role="bold">Execute</emphasis>. If the
839 <emphasis role="bold">Script Type</emphasis> remains unset, the
840 script will be deleted regardless of its type.</para>
841 </listitem>
842 </orderedlist>
843 </section>
844 </section>
845
846 <section id="wireless_access_point">
847 <title>Wireless Access Point</title>
848
849 <para>The Wireless AP Screen from the Enea Edge Management Configuration
850 menu allows users to configure a <literal>Wireless Access Point</literal>.
851 A <literal>wap-capable</literal> interface and a LAN bridge must be added
852 before doing the Wireless AP configuration. For more details see sections
853 <link linkend="wap_interface_type">Wap interface Type</link> and <link
854 linkend="dataplane_bridge">Data-plane bridge</link>.</para>
855
856 <para>The following parameters are configurable:</para>
857
858 <itemizedlist>
859 <listitem>
860 <para>SSID: the Wireless network name - any string with a max. length
861 of 32 octets.</para>
862 </listitem>
863
864 <listitem>
865 <para>Interface Name: the <literal>wap-capable</literal> external
866 interface.</para>
867 </listitem>
868
869 <listitem>
870 <para>Lan Bridge: the LAN bridge where wireless clients will be
871 hosted.</para>
872 </listitem>
873
874 <listitem>
875 <para>WAP Security Mode: <literal>open</literal> or
876 <literal>wpa2Psk</literal>. When choosing <literal>wpa2Psk</literal>,
877 a <literal>password</literal> and an <literal>encryption</literal>
878 must be provided. The <literal>password</literal> can be any string
879 with a minimum length of 8 and a maximum length of 63
880 characters.</para>
881 </listitem>
882
883 <listitem>
884 <para>DHCP Server: <literal>disabled</literal> or
885 <literal>enabled</literal>. When <literal>enabled</literal> is
886 selected, the range of IPs (<literal>IP Address Start</literal> -
887 <literal>IP Address End</literal>), <literal>Netmask</literal> and
888 <literal>Gateway</literal> values must be provided.</para>
889 </listitem>
890 </itemizedlist>
891
892 <figure>
893 <title>Wireless AP</title>
894
895 <mediaobject>
896 <imageobject>
897 <imagedata align="center" contentwidth="600"
898 fileref="images/wap_wireless_ap.png" />
899 </imageobject>
900 </mediaobject>
901 </figure>
902
903 <note>
904 <para>Only a single Wireless AP is allowed on a physical interface. The
905 validation of the <literal>wap-capable</literal> interface is done when
906 adding the Wireless AP, so, in case of an error, the parameters of the
907 <literal>wap-capable</literal> interface must be rechecked. This can be
908 done by accessing the <emphasis role="bold">Configuration</emphasis>
909 menu and selecting <emphasis role="bold">External
910 Interfaces</emphasis>.</para>
911 </note>
912 </section>
913</chapter> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/doc/troubleshooting.xml b/doc/book-enea-edge-getting-started/doc/troubleshooting.xml
new file mode 100644
index 0000000..fcf991e
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/troubleshooting.xml
@@ -0,0 +1,228 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<chapter id="troubleshooting">
3 <title>Troubleshooting and Recovery</title>
4
5 <para>In all scenarios where possible, collect the logs for debugging. More
6 information on log collecting can be found in <olink
7 targetdoc="book_enea_edge_getting_started" targetptr="log_collector">Using
8 the Log Collector in the <xi:include
9 href="../../s_docbuild/olinkdb/pardoc-names.xml"
10 xmlns:xi="http://www.w3.org/2001/XInclude"
11 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
12 Manual.</para>
13
14 <para>The following is a small list of possible Enea Edge problems, and
15 their solutions. If you encounter other issues or can't get Enea Edge to
16 work successfully after consulting the information below, please use the
17 <olink targetdoc="book_enea_edge_release_info"
18 targetptr="contacting_enea_support">Enea Support Team Form, available in the
19 <xi:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
20 xmlns:xi="http://www.w3.org/2001/XInclude"
21 xpointer="element(book_enea_edge_release_info/1)" /></olink> Manual
22 downloaded with your release.</para>
23
24 <table>
25 <title>Troubleshooting and Recovery</title>
26
27 <tgroup cols="2">
28 <colspec align="left" />
29
30 <thead>
31 <row>
32 <entry align="center">Enea Edge Problem</entry>
33
34 <entry align="center">Solution</entry>
35 </row>
36 </thead>
37
38 <tbody>
39 <row>
40 <entry>A uCPE device fails to connect to the Enea Edge Management
41 application after installation.</entry>
42
43 <entry>If the uCPE device is not able to connect to the Enea Edge
44 Management application after an installation, the Web-installer
45 application is started automatically on the uCPE device to change
46 the configuration via a web browser. Please see <olink
47 targetdoc="book_enea_edge_getting_started"
48 targetptr="boot_device_add_map">Booting the uCPE device and adding
49 it to the Map in the <xi:include
50 href="../../s_docbuild/olinkdb/pardoc-names.xml"
51 xmlns:xi="http://www.w3.org/2001/XInclude"
52 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
53 Manual.</entry>
54 </row>
55
56 <row>
57 <entry>The uCPE Device cannot boot after an upgrade.</entry>
58
59 <entry><orderedlist>
60 <listitem>
61 <para>Perform a hardware reboot of the uCPE Device and select
62 the previous Enea Edge Runtime image from the GRUB menu. This
63 action assumes physical access to the uCPE device.</para>
64 </listitem>
65
66 <listitem>
67 <para>Reinitiate the Upgrade procedure according to the steps
68 in section <olink targetdoc="book_enea_edge_getting_started"
69 targetptr="upgrade_devices">uCPE device upgrades in the
70 <xi:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
71 xmlns:xi="http://www.w3.org/2001/XInclude"
72 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
73 Manual.</para>
74 </listitem>
75 </orderedlist></entry>
76 </row>
77
78 <row>
79 <entry>After a failed uCPE device upgrade the previous Enea Edge
80 Runtime image (from the GRUB menu) does not boot.</entry>
81
82 <entry>Reinstall Enea Edge Runtime on the uCPE device and redeploy
83 the initial configuration and virtualized services, by following the
84 steps in <olink targetdoc="book_enea_edge_getting_started"
85 targetptr="install_ena_device">Installing Enea Edge - uCPE Device
86 installation in the <xi:include
87 href="../../s_docbuild/olinkdb/pardoc-names.xml"
88 xmlns:xi="http://www.w3.org/2001/XInclude"
89 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
90 Manual.</entry>
91 </row>
92
93 <row>
94 <entry>The Enea Edge Management application upgrade fails and a
95 working snapshot is available.</entry>
96
97 <entry>If a working snapshot obtained during a previous Upgrade or
98 Uninstall is available
99 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>):
100 <orderedlist>
101 <listitem>
102 <para>Cleanup the current upgrade attempt with:</para>
103
104 <programlisting>./cleanup.sh /opt/ems</programlisting>
105 </listitem>
106
107 <listitem>
108 <para>Restore the previous installation as described in <olink
109 targetdoc="book_enea_edge_getting_started"
110 targetptr="restore_prev_ucpe_install">Restoring a previous
111 Enea Edge Management installation in the <xi:include
112 href="../../s_docbuild/olinkdb/pardoc-names.xml"
113 xmlns:xi="http://www.w3.org/2001/XInclude"
114 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
115 Manual.</para>
116 </listitem>
117 </orderedlist></entry>
118 </row>
119
120 <row>
121 <entry>The Enea Edge Management application upgrade fails and no
122 working snapshot is available, but a System Back-up file
123 exists.</entry>
124
125 <entry><orderedlist>
126 <listitem>
127 <para>Cleanup the current upgrade attempt with:</para>
128
129 <programlisting>./cleanup.sh /opt/ems</programlisting>
130 </listitem>
131
132 <listitem>
133 <para>Perform an installation with the restore option of a
134 previous Enea Edge Management configuration as described in
135 <olink targetdoc="book_enea_edge_getting_started"
136 targetptr="install_ucpemg_from_backup">Installation of the
137 Enea Edge Management application using a System Back-up in the
138 <xi:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
139 xmlns:xi="http://www.w3.org/2001/XInclude"
140 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
141 Manual.</para>
142 </listitem>
143 </orderedlist></entry>
144 </row>
145
146 <row>
147 <entry>The uCPE device is booted, the SSH connection is available
148 but the device is not connected to the Enea Edge Management
149 application.</entry>
150
151 <entry><orderedlist>
152 <listitem>
153 <para>Perform a hardware reboot on the uCPE device to
154 reinitiate the connection mechanism.</para>
155 </listitem>
156
157 <listitem>
158 <para>Use the <emphasis role="bold">Reconnect</emphasis>
159 button from the Enea Edge Management applications's
160 GUI.</para>
161 </listitem>
162
163 <listitem>
164 <para>Connect to the uCPE Device console and run the factory
165 reset script:</para>
166
167 <programlisting>/usr/local/odm/bin/factory_reset.sh</programlisting>
168 </listitem>
169
170 <listitem>
171 <para>If the above actions do not work, reinstall and
172 reconfigure the device using the steps provided in <olink
173 targetdoc="book_enea_edge_getting_started"
174 targetptr="install_ena_device">Installing Enea Edge - uCPE
175 Device installation in the <xi:include
176 href="../../s_docbuild/olinkdb/pardoc-names.xml"
177 xmlns:xi="http://www.w3.org/2001/XInclude"
178 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
179 Manual.</para>
180 </listitem>
181 </orderedlist></entry>
182 </row>
183
184 <row>
185 <entry>The SSH connection to the device cannot be
186 established.</entry>
187
188 <entry>Perform a hardware reboot on the uCPE device. If the problem
189 is not fixed, reinstall and reconfigure the device using the steps
190 provided in <olink targetdoc="book_enea_edge_getting_started"
191 targetptr="install_ena_device">Installing Enea Edge - uCPE Device
192 installation in the <xi:include
193 href="../../s_docbuild/olinkdb/pardoc-names.xml"
194 xmlns:xi="http://www.w3.org/2001/XInclude"
195 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
196 Manual.</entry>
197 </row>
198
199 <row>
200 <entry>The VNF Service is not working as expected after
201 reconfiguration (e.g. a VNF chain is malfunctioning).</entry>
202
203 <entry><orderedlist>
204 <listitem>
205 <para>Undo all flows and/or configuration changes in order to
206 move the system to a previously working configuration.</para>
207 </listitem>
208
209 <listitem>
210 <para>Reboot the device by accessing <emphasis
211 role="bold">Operations</emphasis> and then selecting <emphasis
212 role="bold">Reboot</emphasis> from within the Enea Edge
213 Management application.</para>
214 </listitem>
215
216 <listitem>
217 <para>If the above actions do not work, redeploy all services.
218 This is done by cleaning up the existing configuration by
219 accessing <emphasis role="bold">Operations</emphasis>, then
220 selecting <emphasis role="bold">Factory Reset</emphasis> for a
221 specific device and redeploying the VNF services.</para>
222 </listitem>
223 </orderedlist></entry>
224 </row>
225 </tbody>
226 </tgroup>
227 </table>
228</chapter> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/doc/upgrade_ena.xml b/doc/book-enea-edge-getting-started/doc/upgrade_ena.xml
new file mode 100644
index 0000000..ac2ebb6
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/upgrade_ena.xml
@@ -0,0 +1,623 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="upgrade_ena">
3 <title>Upgrading Enea Edge</title>
4
5 <para>Enea provides regular releases that will require the upgrading of Enea
6 Edge components. The Enea Edge Management application must be upgraded
7 first, followed by upgrading the Enea Edge Runtime on the uCPE
8 devices.</para>
9
10 <section id="upgrade_mg">
11 <title>Upgrading the Enea Edge Management application</title>
12
13 <note>
14 <para>It is recommended to create a system backup by accessing the
15 <emphasis role="bold">System</emphasis> menu and selecting <emphasis
16 role="bold">System Backup</emphasis> from the Enea Edge Management GUI,
17 for recovery in case of an upgrade failure.</para>
18 </note>
19
20 <orderedlist>
21 <listitem>
22 <para>Extract the
23 <filename>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
24 folder.</para>
25
26 <para>The directory in which the archive has been unpacked will be
27 denoted as <literal>&lt;uCPEM-installerdir&gt;</literal>.</para>
28 </listitem>
29
30 <listitem>
31 <para>Enter <literal>&lt;uCPEM-installerdir&gt;/dist</literal>.</para>
32 </listitem>
33
34 <listitem>
35 <para>Run the following command with the root account and change
36 <literal>/opt/ems</literal> to the correct location of the Enea Edge
37 Management installation:</para>
38
39 <programlisting>./upgrade.sh /opt/ems \
40Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
41 </listitem>
42 </orderedlist>
43
44 <para>Running this command will:</para>
45
46 <itemizedlist>
47 <listitem>
48 <para>Stop the currently running <literal>ucpemanager</literal>
49 service.</para>
50 </listitem>
51
52 <listitem>
53 <para>Create a compressed file of the <literal>ucpemanager</literal>
54 application folder
55 (<filename>ucpemanager-Back-up-YYYYddMMHHmm.tar.gz</filename>), which
56 contains a snapshot of the existing installation in the
57 <literal>&lt;uCPEM-installerdir&gt;/dist</literal> directory.</para>
58
59 <note>
60 <para>The snapshot file created during the upgrade can be used for
61 restoring the Enea Edge Management application.</para>
62 </note>
63 </listitem>
64
65 <listitem>
66 <para>Extract the application files from the specified compressed
67 install kit.</para>
68 </listitem>
69
70 <listitem>
71 <para>Start the <literal>ucpemanager</literal> service.</para>
72 </listitem>
73 </itemizedlist>
74
75 <para><olink targetdoc="book_enea_edge_getting_started"
76 targetptr="fresh_ucpemg_install">Fresh Installation of the Enea Edge
77 Management in the <ns:include
78 href="../../s_docbuild/olinkdb/pardoc-names.xml"
79 xmlns:ns="http://www.w3.org/2001/XInclude"
80 xpointer="element(book_enea_edge_getting_started/1)" /></olink> Manual
81 contains information about the input required to be entered during the
82 execution of the upgrade script.</para>
83
84 <para condition="hidden">For an example on how to upgrade an Enea Edge
85 Management installation in a High Availability setup, consult <olink
86 targetdoc="book_enea_edge_getting_started"
87 targetptr="ha_upgrade">Upgrading a High Availability Deployment in the
88 <ns:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
89 xmlns:ns="http://www.w3.org/2001/XInclude"
90 xpointer="element(book_enea_edge_getting_started/1)" /></olink>
91 Manual.</para>
92
93 <section id="restore_prev_ucpe_install">
94 <title>Restoring a previous Enea Edge Management Installation</title>
95
96 <para><emphasis role="bold">How to restore a previous Enea Edge
97 Management installation</emphasis></para>
98
99 <orderedlist>
100 <listitem>
101 <para>Extract
102 <filename>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename></para>
103 </listitem>
104
105 <listitem>
106 <para>The directory in which the archive has been unpacked will be
107 denoted as <literal>&lt;uCPEM-installerdir&gt;</literal>.</para>
108 </listitem>
109
110 <listitem>
111 <para>Copy the snapshot file
112 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>)
113 created during a previous Enea Edge Management Upgrade or Enea Edge
114 Management Uninstall Operation into the
115 <literal>&lt;uCPEM-installerdir&gt;/dist</literal> directory.</para>
116 </listitem>
117
118 <listitem>
119 <para>Enter <literal>&lt;uCPEM-installerdir&gt;/dist</literal>.</para>
120 </listitem>
121
122 <listitem>
123 <para>Run the following command with the root user and change
124 <literal>/opt/ems</literal> to the correct location of the Enea Edge
125 Management installation:</para>
126
127 <programlisting>./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz</programlisting>
128 </listitem>
129 </orderedlist>
130
131 <para>Running this command will:</para>
132
133 <itemizedlist>
134 <listitem>
135 <para>Remove any vestiges of the existing
136 <literal>ucpemanager</literal> service, if they exist.</para>
137 </listitem>
138
139 <listitem>
140 <para>Reinstall the Enea Edge Management application on the
141 specified target location, restoring the data in the database and
142 files in the process.</para>
143 </listitem>
144 </itemizedlist>
145
146 <para>The <literal>ucpemanager</literal> service will then start with
147 the older version now running on the system.</para>
148 </section>
149
150 <section id="uninstall_ucpem_install">
151 <title>Uninstalling an existing Enea Edge Management
152 Installation</title>
153
154 <para><emphasis role="bold">How to uninstall an existing Enea Edge
155 Management installation</emphasis></para>
156
157 <orderedlist>
158 <listitem>
159 <para>Navigate to the folder where the Enea Edge Management
160 application is unpacked:
161 <filename>&lt;uCPEM-installerdir&gt;</filename>.</para>
162 </listitem>
163
164 <listitem>
165 <para>Enter
166 <literal>&lt;uCPEM-installerdir&gt;/dist</literal>.</para>
167 </listitem>
168
169 <listitem>
170 <para>Run the following command with the root user and change
171 <literal>/opt/ems</literal> to the correct location of the Enea Edge
172 Management installation:</para>
173
174 <programlisting>./uninstall.sh /opt/ems</programlisting>
175 </listitem>
176 </orderedlist>
177
178 <para>Running this command will:</para>
179
180 <itemizedlist>
181 <listitem>
182 <para>Stop the currently running <literal>ucpemanager</literal>
183 service.</para>
184 </listitem>
185
186 <listitem>
187 <para>Create a compressed file of the <literal>ucpemanager</literal>
188 application folder:
189 <filename>ucpemanager-Back-up-YYYYddMMHHmm.tar.gz</filename>, which
190 contains a snapshot of the existing installation and functions as a
191 restore point.</para>
192
193 <note>
194 <para>The snapshot file created during the uninstall can be used
195 for restoring the Enea Edge Management application.</para>
196 </note>
197 </listitem>
198
199 <listitem>
200 <para>Uninstall the <literal>ucpemanager</literal> service, so that
201 it will not start up on reboot.</para>
202 </listitem>
203
204 <listitem>
205 <para>Uninstall the database service.</para>
206 </listitem>
207
208 <listitem>
209 <para>Completely remove the contents of the application and database
210 folders.</para>
211 </listitem>
212 </itemizedlist>
213
214 <para>After these steps, the Enea Edge Management application is
215 completely removed from the system.</para>
216 </section>
217 </section>
218
219 <section id="upgrade_devices">
220 <title>uCPE device Upgrades</title>
221
222 <para>A uCPE device can be upgraded using the Enea Edge Management
223 GUI.</para>
224
225 <section id="device_up_process">
226 <title>The uCPE device Upgrade Process</title>
227
228 <para>The Device Upgrade/Install option performs the following
229 operations to the uCPE device:</para>
230
231 <orderedlist>
232 <listitem>
233 <para><emphasis role="bold">Prepare for upgrade.</emphasis> This
234 stage prepares the files needed for an upgrade.</para>
235 </listitem>
236
237 <listitem>
238 <para><emphasis role="bold">Install file on device.</emphasis> This
239 stage copies the file to the uCPE device.</para>
240 </listitem>
241
242 <listitem>
243 <para><emphasis role="bold">Upgrade Device.</emphasis> This stage
244 upgrades the uCPE device to a newer version.</para>
245 </listitem>
246 </orderedlist>
247
248 <note>
249 <para>Upgrading from Enea NFV Access 2.3.0 is not possible when using
250 the Enea Edge Management application in HTTPS mode. Either switch to
251 HTTP by accessing the <emphasis role="bold">System</emphasis> menu,
252 clicking on <emphasis role="bold">Configuration</emphasis>, then
253 <emphasis role="bold">Web Access</emphasis> and checking the <emphasis
254 role="bold">Enable HTTP</emphasis> box, or by installing Edge Enea
255 2.4.0 on the device manually.</para>
256 </note>
257 </section>
258
259 <section id="mg_upgrade">
260 <title>Managing the uCPE device Upgrade</title>
261
262 <para>Before an installation or upgrade can be completed, certain
263 configuration data must be set. Files also need to be uploaded to the
264 Device Upgrade image repository in order to be uploaded to the
265 device.</para>
266
267 <para>Launch the Device Upgrade management console by selecting
268 <emphasis role="bold">Devices</emphasis> and then the <emphasis
269 role="bold">Upgrade</emphasis> button from the top tool-bar. The console
270 will contain the following tabs:</para>
271
272 <itemizedlist>
273 <listitem>
274 <para><emphasis role="bold">Image Library</emphasis>. To add/delete
275 an image.</para>
276 </listitem>
277
278 <listitem>
279 <para><emphasis role="bold">Upgrade Operations</emphasis>. See
280 upgrades that are currently running, cancel any upgrades in
281 progress, or start a uCPE device upgrade.</para>
282 </listitem>
283
284 <listitem>
285 <para><emphasis role="bold">Configuration</emphasis>. Upgrade
286 configuration parameters.</para>
287 </listitem>
288 </itemizedlist>
289
290 <note>
291 <para>The uCPE Device upgrade is done with image files of the type
292 <literal>rootfs.ostree.tar.bz2</literal>, which are available in the
293 <filename>Enea_Edge_Runtime_&lt;processor&gt;_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
294 file you downloaded with your release.</para>
295 </note>
296
297 <section id="image_lib">
298 <title>Image Library</title>
299
300 <para><emphasis role="bold">Adding an image to the image
301 repository/library</emphasis><orderedlist>
302 <listitem>
303 <para>Select <emphasis role="bold">Devices</emphasis> and then
304 the <emphasis role="bold">Upgrade</emphasis> button.</para>
305 </listitem>
306
307 <listitem>
308 <para>Select <emphasis role="bold">Add</emphasis> from the
309 <emphasis role="bold">Image Library</emphasis> tab to add a new
310 image file.</para>
311 </listitem>
312
313 <listitem>
314 <para>Select <emphasis role="bold">Choose File</emphasis> to
315 provide the path to the image file (must be of type
316 <literal>rootfs.os-tree.tar.bz2</literal>).</para>
317 </listitem>
318
319 <listitem>
320 <para>Select the target hardware platform corresponding to the
321 image being uploaded (<literal>xeon-d</literal> or
322 <literal>atom-c3000</literal>).</para>
323 </listitem>
324
325 <listitem>
326 <para>Click <emphasis role="bold">Send</emphasis> to upload the
327 image to the image repository.</para>
328 </listitem>
329 </orderedlist></para>
330
331 <para><emphasis role="bold">Deleting an image from the image
332 repository</emphasis></para>
333
334 <orderedlist>
335 <listitem>
336 <para>Select <emphasis role="bold">Devices</emphasis> and then the
337 <emphasis role="bold">Upgrade</emphasis> button.</para>
338 </listitem>
339
340 <listitem>
341 <para>Select the image you want to delete from the <emphasis
342 role="bold">Image Library</emphasis> tab and then click <emphasis
343 role="bold">Delete</emphasis>.</para>
344 </listitem>
345 </orderedlist>
346 </section>
347
348 <section id="upgrade_options">
349 <title>Upgrade Operations</title>
350
351 <para>The <emphasis role="bold">Upgrade Operations</emphasis> tab
352 allows a user to manage uCPE device upgrades in the system. It allows
353 the user to see all the upgrades that are currently in progress, as
354 well as listing the completed ones. If an upgrade succeeds or fails,
355 then a row will be added to the completed upgrades table. If one
356 fails, the failure message will be visible in the table.</para>
357
358 <note>
359 <para>The list of completed upgrade tasks resides in the cache
360 memory and will not persist across reboots of the server.</para>
361 </note>
362
363 <para><emphasis role="bold">How to Install/Upgrade a device
364 immediately or schedule the process for later</emphasis><orderedlist>
365 <listitem>
366 <para>Select <emphasis role="bold">Devices</emphasis> and then
367 the <emphasis role="bold">Upgrade</emphasis> button.</para>
368 </listitem>
369
370 <listitem>
371 <para>Select <emphasis role="bold">Upgrade Devices</emphasis>
372 from the <emphasis role="bold">Upgrade Operations</emphasis>
373 tab. This will launch a <literal>Multi Device Install
374 Image</literal> screen that will allow the user to install and
375 upgrade more than one uCPE device at a time or upgrade
376 later.</para>
377 </listitem>
378 </orderedlist></para>
379
380 <para>The configurable parameters are:</para>
381
382 <itemizedlist>
383 <listitem>
384 <para><literal>Scheduling</literal>. Click this checkbox if the
385 upgrade will be done later. Schedule the day, hour and minute for
386 when to run the upgrade.</para>
387
388 <note>
389 <para>The hour represents the local Enea Edge Management
390 application server hour.</para>
391 </note>
392 </listitem>
393
394 <listitem>
395 <para><literal>Description</literal>. An optional description of
396 the operation. It is recommended to add a description so that
397 different upgrades happening simultaneously can be
398 distinguished.</para>
399 </listitem>
400
401 <listitem>
402 <para><literal>Image File</literal>. Click on <emphasis
403 role="bold">Choose Image File</emphasis> to select the image
404 file.</para>
405 </listitem>
406
407 <listitem>
408 <para><literal>Devices</literal>. The list of uCPE Devices that
409 can accept an image file is populated when the image file is
410 chosen.</para>
411
412 <para>Mark the uCPE devices that you wish to upgrade and press the
413 <emphasis role="bold">&gt;</emphasis> button to move the uCPE
414 devices to the right side of the selector. Those chosen form the
415 list of uCPE devices that will be upgraded.</para>
416 </listitem>
417
418 <listitem>
419 <para><literal>Upgrade Operation</literal>. The available options
420 are:</para>
421
422 <itemizedlist>
423 <listitem>
424 <para><literal>Install and Activate</literal>. This will do an
425 image installation as well as an upgrade.</para>
426 </listitem>
427
428 <listitem>
429 <para><literal>Install Only</literal>. This will do an image
430 installation only. The image is copied to the uCPE device, and
431 an upgrade will be done later either at a scheduled time or
432 when the option <literal>Activate Only</literal> is
433 selected.</para>
434 </listitem>
435
436 <listitem>
437 <para><literal>Activate Only</literal>. This will activate an
438 already installed image on the uCPE device.</para>
439 </listitem>
440 </itemizedlist>
441 </listitem>
442
443 <listitem>
444 <para>To start the upgrade, click <emphasis
445 role="bold">ok</emphasis>.</para>
446 </listitem>
447 </itemizedlist>
448
449 <note>
450 <para>When the uCPE device activates the upgrade, it will be
451 rebooted automatically.</para>
452 </note>
453 </section>
454
455 <section id="releases_installed">
456 <title>Releases installed on a uCPE device</title>
457
458 <para>The installed releases on a uCPE device can be viewed by
459 selecting the uCPE device first, then from the top toolbar selecting
460 <emphasis role="bold">Configuration</emphasis> and then the <emphasis
461 role="bold">Upgrade</emphasis> button.</para>
462
463 <para>The installed releases on the uCPE device, the release status,
464 release state, <literal>commit-id</literal> and release version will
465 be listed in a table.</para>
466 </section>
467
468 <section id="upgrade_status">
469 <title>uCPE device Upgrade Status</title>
470
471 <para>The status of the installation and upgrade can be viewed in the
472 <emphasis role="bold">Upgrade Operations</emphasis> tab. Ongoing or
473 scheduled upgrade operations can be viewed or cancelled.</para>
474
475 <para><emphasis role="bold">To view the status of an installation or
476 upgrade operations</emphasis></para>
477
478 <orderedlist>
479 <listitem>
480 <para>Select <emphasis role="bold">Devices</emphasis> and then the
481 <emphasis role="bold">Upgrade</emphasis> button.</para>
482 </listitem>
483
484 <listitem>
485 <para>Select <emphasis role="bold">Upgrade Operations</emphasis>.
486 The ongoing operations are listed at the top and a history of
487 failed or successful operations are listed at the bottom.</para>
488 </listitem>
489
490 <listitem>
491 <para>Select an <emphasis role="bold">Active</emphasis> or
492 <emphasis role="bold">Completed Upgrade Operation</emphasis> and
493 then the <emphasis role="bold">Device Status</emphasis> button to
494 see detailed information regarding the upgrade operation,
495 including the uCPE devices involved and information per uCPE
496 device.</para>
497 </listitem>
498 </orderedlist>
499
500 <para><emphasis role="bold">To cancel an upgrade
501 operation</emphasis></para>
502
503 <orderedlist>
504 <listitem>
505 <para>Select <emphasis role="bold">Devices</emphasis>, then the
506 <emphasis role="bold">Upgrade</emphasis> button and choose
507 <emphasis role="bold">Upgrade Operations</emphasis>.</para>
508 </listitem>
509
510 <listitem>
511 <para>Select an operation from the list and choose <emphasis
512 role="bold">Cancel Upgrade</emphasis> and <emphasis
513 role="bold">Confirm</emphasis>. The operation will then be deleted
514 from the list.</para>
515 </listitem>
516 </orderedlist>
517 </section>
518
519 <section id="config">
520 <title>Configuration</title>
521
522 <note>
523 <para>The default values present in the configuration of each uCPE
524 device are recommended for use. Modifying them is for an <emphasis
525 role="bold">Advanced User</emphasis> only.</para>
526 </note>
527
528 <para><emphasis role="bold">How to Configure the uCPE device
529 Upgrade</emphasis><orderedlist>
530 <listitem>
531 <para>Select <emphasis role="bold">Devices</emphasis> and then
532 the <emphasis role="bold">Upgrade</emphasis> button.</para>
533 </listitem>
534
535 <listitem>
536 <para>Select <emphasis
537 role="bold">Configuration</emphasis>.</para>
538 </listitem>
539
540 <listitem>
541 <para>The configurable parameters are:</para>
542
543 <itemizedlist>
544 <listitem>
545 <para><literal>deviceImageDir</literal>. This is the disk
546 location of the device image repository.</para>
547
548 <note>
549 <para>If no absolute path name is given it is assumed to
550 be relative to the installation directory.</para>
551 </note>
552 </listitem>
553
554 <listitem>
555 <para><literal>maxThreads</literal>. This number dictates
556 how many upgrades the system can manage at one time, either
557 individually launched or launched from the multi-device
558 screens. This value defaults to 20, which means that 20 uCPE
559 devices may be updated at one time.</para>
560 </listitem>
561
562 <listitem>
563 <para><literal>KeepAlive</literal>. This number represents
564 the number of seconds that a thread will be kept alive
565 before it is collected. If multiple installations are
566 occurring, this will keep the thread alive for X seconds
567 before it is released. If not released, it can be used by
568 the internal scheduling system as soon as it has completed
569 an upgrade.</para>
570 </listitem>
571 </itemizedlist>
572 </listitem>
573 </orderedlist></para>
574 </section>
575
576 <section id="related_functionality">
577 <title>Related Functionality for a uCPE device Upgrade</title>
578
579 <para>Each uCPE device can receive image files and use them to
580 upgrade. This can be done by selecting the uCPE device in the
581 <emphasis role="bold">System</emphasis> view and clicking the
582 <emphasis role="bold">Upgrade</emphasis> button. In the new window, an
583 upgrade image can be chosen from the <emphasis role="bold">Image
584 Files</emphasis> tab by selecting the image file from the list and
585 clicking the <emphasis role="bold">Install on Device</emphasis>
586 button. The Image files that appear in the <emphasis role="bold">Image
587 Library</emphasis> tab can be uploaded to the Enea Edge Management
588 Application by following the steps listed in <link
589 linkend="image_lib">Image Library</link>.</para>
590
591 <para>Once an image is installed on the uCPE device, the image will be
592 available on the uCPE device and be visible in the <emphasis
593 role="bold">Releases</emphasis> tab. There are two ways to make it
594 active, choose one or the other:</para>
595
596 <itemizedlist>
597 <listitem>
598 <para>Select it from the list and then start the upgrade by
599 clicking the <emphasis role="bold">Upgrade</emphasis>
600 button.</para>
601 </listitem>
602
603 <listitem>
604 <para>Select <emphasis role="bold">Operations</emphasis>, then
605 <emphasis role="bold">Upgrade</emphasis>, enter the
606 <literal>Release Name</literal> and press <emphasis
607 role="bold">Execute</emphasis>. Filling in the <literal>Restore
608 Archive</literal> text field is optional and should be left unset
609 if the <literal>NFVi Snapshot</literal> feature is
610 disabled.</para>
611 </listitem>
612 </itemizedlist>
613
614 <para>If an installed image is no longer needed, it can be removed
615 from the device by selecting <emphasis
616 role="bold">Operations</emphasis> and <emphasis role="bold">Remove
617 Release</emphasis>. In the <emphasis role="bold">Remove
618 Release</emphasis> window, provide the <literal>Release Name</literal>
619 and press <emphasis role="bold">Execute</emphasis>.</para>
620 </section>
621 </section>
622 </section>
623</chapter> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/doc/vnf_mg.xml b/doc/book-enea-edge-getting-started/doc/vnf_mg.xml
new file mode 100644
index 0000000..058be40
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/vnf_mg.xml
@@ -0,0 +1,529 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<chapter id="vnf_mg">
3 <title>VNF Management</title>
4
5 <para>The Enea Edge Management application is responsible for onboarding,
6 configuring (e.g. CloudInit) and ensuring life cycle management of VNFs that
7 are instantiated and run on various uCPE devices.</para>
8
9 <section id="onboarding_a_vnf">
10 <title>Onboarding a VNF</title>
11
12 <para>The onboarding of a VNF means adding it to the Enea Edge Management
13 application VNF Catalogue and preparing it for instantiation (deployment
14 on connected uCPE devices). This is accomplished using the Enea Edge
15 Management Onboarding graphical user interface.</para>
16
17 <para>Typically, the Getting Started Guide of a VNF, provided by the VNF
18 vendor, contains all necessary information needed to onboard a VNF.</para>
19
20 <section id="retrieve_art">
21 <title>Retrieving Artifacts</title>
22
23 <para>The user must first retrieve the necessary artifacts from the VNF
24 vendor:</para>
25
26 <orderedlist>
27 <listitem>
28 <para>Download the VNF from the commercial vendor.</para>
29 </listitem>
30
31 <listitem>
32 <para>Procure any VNF-specific files from the VNF vendor, e.g.
33 license file.</para>
34
35 <note>
36 <para>There are no standard ways of managing VNF licenses,
37 therefore no general guidelines can be provided. One example of
38 license handling that can be employed in the Enea Edge Management
39 application is the adding of a license during the Cloud-Init
40 setup.</para>
41 </note>
42 </listitem>
43
44 <listitem>
45 <para>Optionally, get access to the VNF specific VNF Manager for day
46 1 and 2 configuration (in cloud or for local deployment).</para>
47 </listitem>
48
49 <listitem>
50 <para>Procure the Getting Started Guide from the VNF vendor,
51 preferably for KVM deployment for VNF specific configuration
52 information.</para>
53 </listitem>
54 </orderedlist>
55 </section>
56
57 <section id="onboard_prep">
58 <title>Preparation</title>
59
60 <para>Once all needed downloadables, documentation and more have been
61 attained, preparation for onboarding must be completed:</para>
62
63 <orderedlist>
64 <listitem>
65 <para>Determine the use-case and performance requirements of the VNF
66 you wish to deploy:</para>
67
68 <itemizedlist spacing="compact">
69 <listitem>
70 <para>This decides what resources the VNF is configured for,
71 along with networking and day zero configurations.</para>
72
73 <note>
74 <para>Generally, the Getting Started Guide for the VNF
75 provides guidelines for resource allocation, but since
76 performance is dependent on hardware capacity, the right
77 resource allocation for deployment is determined through
78 benchmarking.</para>
79 </note>
80 </listitem>
81
82 <listitem>
83 <para>Determine the amount of hardware resources needed for the
84 VNF (RAM, number of CPUs and storage size).</para>
85 </listitem>
86
87 <listitem>
88 <para>Determine how many Virtual Network Interfaces the VNF will
89 use.</para>
90 </listitem>
91 </itemizedlist>
92 </listitem>
93
94 <listitem>
95 <para>Determine the Day-0 configuration method from the VNF Getting
96 Started guidelines.</para>
97
98 <note>
99 <para>For many VNFs, day zero configuration can be skipped in
100 early onboarding efforts when automation is not of
101 importance.</para>
102 </note>
103 </listitem>
104
105 <listitem>
106 <para>Determine any requirements needed by the Cloud-Init file
107 structure and the content needed when this structure is used.</para>
108 </listitem>
109 </orderedlist>
110 </section>
111
112 <section id="onboard_in_ucpemg">
113 <title>Onboarding into the Enea Edge Management application</title>
114
115 <para><emphasis role="bold">How to onboard a VNF into the Enea Edge
116 Management application</emphasis></para>
117
118 <orderedlist>
119 <listitem>
120 <para>Select from the top toolbar <emphasis
121 role="bold">VNF</emphasis> and then <emphasis
122 role="bold">Descriptors</emphasis>.</para>
123 </listitem>
124
125 <listitem>
126 <para>Click the <emphasis role="bold">Onboard</emphasis>
127 button.</para>
128 </listitem>
129 </orderedlist>
130
131 <para>This window contains data fields where both necessary and optional
132 information about the VNF can be supplied. After doing so, press the
133 Onboard button and the Enea Edge Management application will create the
134 VNF descriptor and add it to its VNF Catalog.</para>
135
136 <figure>
137 <title>Onboard a VNF</title>
138
139 <mediaobject>
140 <imageobject>
141 <imagedata align="center" contentwidth="600"
142 fileref="images/onboard_a_vnf_image.png" />
143 </imageobject>
144 </mediaobject>
145 </figure>
146
147 <para><emphasis role="bold">Main fields</emphasis></para>
148
149 <itemizedlist>
150 <listitem>
151 <para><emphasis role="bold">VM Image File</emphasis>. This is the
152 Virtual Machine image file for the VNF. Typically, it is a QCOW
153 image. Press <emphasis role="bold">Choose File</emphasis> and select
154 the image you wish to upload.</para>
155 </listitem>
156
157 <listitem>
158 <para><emphasis role="bold">Image Format</emphasis>. Select the
159 format which matches the image file format.</para>
160 </listitem>
161
162 <listitem>
163 <para><emphasis role="bold">VNF Type Name</emphasis>. This is the
164 name that will be used to identify this VNF. It will be shown in the
165 VNFs list.</para>
166 </listitem>
167
168 <listitem>
169 <para><emphasis role="bold">Description</emphasis>. This field
170 contains any description provided and is only displayed in the GUI
171 tables in the Enea Edge Management application.</para>
172 </listitem>
173
174 <listitem>
175 <para><emphasis role="bold">Version</emphasis>. This is the version
176 of the current VNF that you are hosting. It's used to distinguish
177 this VNF from other versions of the same type.</para>
178 </listitem>
179
180 <listitem>
181 <para><emphasis role="bold">Memory in MB</emphasis>. This is the
182 amount of memory (in megabytes) that will be provided to this type
183 of VNF when it is instantiated. To determine the value for this
184 field, consult the VNF vendor.</para>
185 </listitem>
186
187 <listitem>
188 <para><emphasis role="bold">Num of CPUs</emphasis>. The number of
189 CPUs that will be dedicated to an instance of this VNF when created.
190 To determine the value for this field, consult the VNF
191 vendor.</para>
192 </listitem>
193
194 <listitem>
195 <para><emphasis role="bold">Storage in GB</emphasis>. How much disk
196 space to provide an instance of this VNF. To determine the value for
197 this field, consult the VNF vendor.</para>
198 </listitem>
199 </itemizedlist>
200
201 <para><emphasis role="bold">Interfaces Tab</emphasis></para>
202
203 <para>Click on the <emphasis role="bold">Interfaces</emphasis> tab to
204 show the Interfaces table.</para>
205
206 <para>This table will contain the interfaces required by this VNF to be
207 configured, when creating an instance. Consult the VNF vendor to
208 determine which and how many are required. Each interface requires a
209 name, and optionally a description, used only by the Enea Edge
210 Management application.</para>
211
212 <note>
213 <para>CAUTION: The user MUST save and use the same order for the
214 virtual interfaces during both the onboarding and instantiation
215 phases.</para>
216 </note>
217
218 <para><emphasis role="bold">Cloud Init Tab</emphasis></para>
219
220 <para>Click the <emphasis role="bold">Cloud Init</emphasis> tab to
221 provide the Cloud-Init configuration. There are three fields that need
222 to be populated:</para>
223
224 <orderedlist>
225 <listitem>
226 <para><emphasis role="bold">Cloud-Init Datasource</emphasis></para>
227
228 <para>To onboard a VNF you must specify the <literal>Cloud-Init
229 Datasource</literal> that the VNF uses. This information is procured
230 from the VNF Vendor. Choose one of the following methods to specify
231 the datasource:</para>
232
233 <itemizedlist spacing="compact">
234 <listitem>
235 <para><emphasis role="bold">None</emphasis>. If there is no
236 datasource.</para>
237 </listitem>
238
239 <listitem>
240 <para><emphasis role="bold">ConfigDrive</emphasis>. This method
241 allows you to provide any number of content-data files
242 containing Cloud-Init data.</para>
243 </listitem>
244
245 <listitem>
246 <para><emphasis role="bold">NoCloud</emphasis>. This is a
247 simpler method that uses only one cloud-init file
248 (User-Data).</para>
249 </listitem>
250
251 <listitem>
252 <para><emphasis role="bold">ISO</emphasis>. Pre-cooked
253 cloud-init image. This image must be created by the user
254 according to VNF requirements.</para>
255 </listitem>
256 </itemizedlist>
257 </listitem>
258
259 <listitem>
260 <para><emphasis role="bold">Cloud-Init Disk Type</emphasis></para>
261
262 <para>The <literal>Cloud-Init Disk Type</literal> field must be set
263 to either <literal>Disk</literal>, or <literal>CD-ROM</literal>,
264 depending on what the VNF requires. You can get this information
265 from the VNF Vendor.</para>
266 </listitem>
267
268 <listitem>
269 <para><emphasis role="bold">Content Files Table</emphasis></para>
270
271 <para>The <literal>Content Files Table</literal> is ONLY used if
272 <literal>ConfigDrive</literal> is chosen as the Cloud-Init
273 Datasource. For each content file added, a <literal>Path</literal>
274 must be provided. When the Enea Edge Management application is used
275 to create an instance for multiple VNFs, the user will be prompted
276 to provide a data file for each entry in this table. Each type of
277 VNF will require different cloud-init files, e.g.: a license file.
278 The data files will be added to the cloud-init image that the user
279 provides at the instantiation of the VNF. If the cloud-init image is
280 not provided, no Cloud-Init Data Source will be created for that VNF
281 and there will be no warning.</para>
282 </listitem>
283 </orderedlist>
284
285 <para>Consult with the VNF vendor to determine what is required for the
286 VNF you are onboarding.</para>
287
288 <para><emphasis role="bold">Properties Tab</emphasis></para>
289
290 <para>In this table, you can enter values for properties that will be
291 used during instantiation of the VNF. The values will augment the
292 default values in the <filename>domain.xml</filename> file used by
293 <literal>libvirt/virsh</literal> (running in Enea Edge) when creating an
294 instance of the VNF. Consult with the VNF Vendor or ENEA support for
295 values needed by specific VNFs.</para>
296
297 <para><emphasis role="bold">Property Values</emphasis></para>
298
299 <itemizedlist>
300 <listitem>
301 <para><literal>numHugePages</literal> defines the number of huge
302 memory pages the VNF uses (for DPDK).</para>
303 </listitem>
304
305 <listitem>
306 <para><literal>vnfMgmtIpAddress</literal>: the IP address of the
307 VNF's management interface, connected to a
308 <literal>vnfMgmt</literal> bridge (e.g. 10.0.0.2).</para>
309 </listitem>
310
311 <listitem>
312 <para><literal>internalMgmtPort</literal>: the VNF's TCP/UDP port
313 used for management (e.g. 443).</para>
314 </listitem>
315
316 <listitem>
317 <para><literal>externalMgmtPort</literal>: the Management port used
318 for external access (e.g. 60001).</para>
319 </listitem>
320 </itemizedlist>
321
322 <note>
323 <para>The last three properties are useful in conjuction with the
324 <literal>vnfMgmt</literal> bridge type. They allow the user to map the
325 internal VNF management port to an external port, useful for VNF
326 configuration from WAN.</para>
327
328 <para>In the previous example, the internal TCP port 443 (HTTPS) was
329 mapped to the external port 60001, which allows the user to access the
330 VNF management port from a web browser e.g.
331 <literal>https://&lt;WAN_IP&gt;:60001</literal>.</para>
332 </note>
333 </section>
334 </section>
335
336 <section id="instantiating_a_vnf">
337 <title>Instantiating a VNF</title>
338
339 <para>When a VNF is onboarded and available in the VNF catalog, it can be
340 instantiated on connected uCPE devices. The configurations provided when
341 the VNF is onboarded, serve as a template for instantiation. Before
342 instantiating any VNF, please make sure the available storage space on the
343 uCPE device is big enough to accommodate the VNF you need to
344 instantiate.</para>
345
346 <para>Follow the instructions below to instantiate a VNF:</para>
347
348 <orderedlist>
349 <listitem>
350 <para>Select from the top toolbar <emphasis role="bold">VNF</emphasis>
351 and choose <emphasis role="bold">Instances</emphasis>.</para>
352 </listitem>
353
354 <listitem>
355 <para>Click the <emphasis role="bold">Add</emphasis> button.</para>
356 </listitem>
357
358 <listitem>
359 <para>Fill out the following mandatory fields:</para>
360
361 <itemizedlist spacing="compact">
362 <listitem>
363 <para>Name: a descriptive name.</para>
364 </listitem>
365
366 <listitem>
367 <para>VNF Type: a list of onboarded VNFs.</para>
368 </listitem>
369
370 <listitem>
371 <para>uCPE Device: the uCPE device to instantiate the VNF
372 on.</para>
373 </listitem>
374
375 <listitem>
376 <para>Networking Configuration:</para>
377
378 <itemizedlist spacing="compact">
379 <listitem>
380 <para>Connect each configured NIC with a bridge, SR-IOV or PCI
381 Passthrough.</para>
382 </listitem>
383
384 <listitem>
385 <para>Set up each NIC with a driver method.</para>
386 </listitem>
387 </itemizedlist>
388
389 <note>
390 <para>All configured NICs must be set up before instantiating a
391 VNF. Failure to do so will end in a failed instantiation.</para>
392 </note>
393 </listitem>
394 </itemizedlist>
395 </listitem>
396
397 <listitem>
398 <para>Add VNF-specific configuration data by uploading a Cloud-Init
399 file (when the Cloud-Init is used).</para>
400 </listitem>
401
402 <listitem>
403 <para>Add any VNF-specific files (e.g license files).</para>
404 </listitem>
405
406 <listitem>
407 <para>Hit the <emphasis role="bold">Create</emphasis> button to deploy
408 the VNF and run it on the specified uCPE device.</para>
409 </listitem>
410 </orderedlist>
411
412 <para>Selecting the <emphasis role="bold">VNF</emphasis> menu then
413 choosing <emphasis role="bold">Events</emphasis> will show that the VNF
414 was created and a connection was established.</para>
415 </section>
416
417 <section id="vm_operations">
418 <title>VNF Instance Operations</title>
419
420 <para>Various operations can be done to a VNF instance. It can be paused,
421 resumed, stopped, started or deleted.</para>
422
423 <orderedlist>
424 <listitem>
425 <para>Select from the top toolbar <emphasis role="bold">VNF</emphasis>
426 and choose <emphasis role="bold">Instances</emphasis>.</para>
427 </listitem>
428
429 <listitem>
430 <para>Select an instance that needs to be modified.</para>
431 </listitem>
432
433 <listitem>
434 <para>Depending on the desired action, click the <emphasis
435 role="bold">Delete/ Force Delete / Start / Stop / Pause /
436 Resume</emphasis> button, respectively.</para>
437 </listitem>
438 </orderedlist>
439
440 <para>Alternatively, these same operations can be performed by:</para>
441
442 <orderedlist>
443 <listitem>
444 <para>Selecting <emphasis role="bold">Operations</emphasis>.</para>
445 </listitem>
446
447 <listitem>
448 <para>Depending on the desired action, choosing <emphasis
449 role="bold">Destroy / Start / Stop / Pause / Resume VM</emphasis>
450 respectively.</para>
451 </listitem>
452
453 <listitem>
454 <para>The <literal>Id</literal> of the VM that should be modified can
455 be found by selecting <emphasis role="bold">Configuration</emphasis>,
456 then <emphasis role="bold">Virtual Machines</emphasis>, and then
457 accessing the <emphasis role="bold">VMs</emphasis> tab.</para>
458 </listitem>
459
460 <listitem>
461 <para>Provide the <literal>Id</literal> of the VM that should be
462 modified and press <emphasis role="bold">Execute</emphasis>.</para>
463 </listitem>
464 </orderedlist>
465 </section>
466
467 <section id="enter_console">
468 <title>Accessing the VNF console</title>
469
470 <para>Once the VNF is deployed, the VNF console can be entered using SSH
471 and virsh commands. The VNF Console is a typical starting point for
472 determining a successful deployment and configuring a VNF beyond Day
473 Zero.</para>
474
475 <orderedlist>
476 <listitem>
477 <para>SSH to the uCPE device from the Enea Edge Management application
478 (access the <emphasis role="bold">Device</emphasis> menu and select
479 <emphasis role="bold">SSH</emphasis>) using:</para>
480
481 <itemizedlist>
482 <listitem>
483 <para>For normal connections: the <literal>Username</literal>
484 (default: root), the <literal>Password</literal> (default: no
485 password), the <literal>Port</literal> (default: 22) and the
486 <literal>Reverse ssh</literal> checkbox: unchecked.</para>
487 </listitem>
488
489 <listitem>
490 <para>For reverse SSH connections (SSH to a uCPE device behind
491 NAT): the <literal>Username</literal> (default: root) and the
492 <literal>Reverse SSH</literal> checkbox checked. The port will be
493 automatically chosen by the Enea Edge Management application in
494 the range defined in the <emphasis role="bold">SSH</emphasis>
495 configuration panel, available when accessing the <emphasis
496 role="bold">System</emphasis> menu, then <emphasis
497 role="bold">Configuration</emphasis> and choosing <emphasis
498 role="bold">Reverse SSH</emphasis> . By default, the start port
499 will be <literal>7000</literal> and the maximum number of ports
500 allocated to all devices is 10. Only one port per device is
501 allowed.</para>
502
503 <para>When the SSH window is closed, the tunnel configuration is
504 deleted on the uCPE device and the tunnel is destroyed, so that
505 the port can be reused to establish a new tunnel when
506 needed.</para>
507 </listitem>
508 </itemizedlist>
509 </listitem>
510
511 <listitem>
512 <para>In SSH:</para>
513
514 <orderedlist spacing="compact">
515 <listitem>
516 <para>Use the <command>virsh list</command> command to list all
517 running VNFs and to determine the VNF's instance number.</para>
518 </listitem>
519
520 <listitem>
521 <para>Use the <command>virsh console &lt;instance
522 number&gt;</command> command to enter the VNF-specific
523 console.</para>
524 </listitem>
525 </orderedlist>
526 </listitem>
527 </orderedlist>
528 </section>
529</chapter> \ No newline at end of file
diff --git a/doc/book-enea-edge-getting-started/swcomp.mk b/doc/book-enea-edge-getting-started/swcomp.mk
new file mode 100755
index 0000000..41e4416
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/swcomp.mk
@@ -0,0 +1,10 @@
1# Component build specification
2
3# Version of THIS book
4BOOK_VER ?= $(REL_VER)-dev
5
6DOCBOOK_SRC := $(COMP)/swcomp.mk $(COMP)/doc/book.xml $(shell find $(COMP)/doc -type f \( -name "*.xml" -o -name "*.svg" -o -name "*.png" \) ! -name "book.xml" -print)
7
8BOOKPACKAGES := book-enea-edge-getting-started
9BOOKDESC_$(BOOKPACKAGES) := "Enea Edge $(PROD_VER) Getting Started"
10BOOKDEFAULTCONDITION := $(DEFAULTCONDITIONS)