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