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.xml266
-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.xml1193
-rw-r--r--doc/book-enea-edge-getting-started/doc/introduction.xml264
-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.xml588
-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, 5397 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..70a9978
--- /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 <section id="high_availability_ig">
421 <title>Installing the Enea Edge Management in High Availability
422 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..05276ed
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/grafana.xml
@@ -0,0 +1,266 @@
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>Docker for CentOS 7 installed on the machine and set to
32 <literal>autostart</literal> as a service.</para>
33 </listitem>
34
35 <listitem>
36 <para>Superuser rights on the CentOS 7 machine.</para>
37 </listitem>
38 </itemizedlist>
39 </section>
40
41 <section id="deploy_steps">
42 <title>Deploying Grafana and InfluxDB</title>
43
44 <para>On the CentOS 7 server open a terminal, log into a bash shell with
45 the root account and perform the following:</para>
46
47 <orderedlist>
48 <listitem>
49 <para>Extract
50 <filename>Enea_Edge_Telemetry_Deploy_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>.</para>
51
52 <para>The directory in which the archive will be unpacked will be
53 denoted as: <literal>&lt;Telemetry-installdir&gt;</literal>.</para>
54 </listitem>
55
56 <listitem>
57 <para>Enter <literal>&lt;Telemetry-installdir&gt;</literal>.</para>
58 </listitem>
59
60 <listitem>
61 <para>Run the provided <filename>telemetry_deploy.sh</filename>
62 script.</para>
63 </listitem>
64
65 <listitem>
66 <para>When prompted, select what images you want to deploy.</para>
67
68 <para>If an image is already deployed, you will be prompted to
69 replace it.</para>
70 </listitem>
71
72 <listitem>
73 <para>During the InfluxDB deployment, you will be prompted to
74 provide a username and password. These must match the ones
75 configured in the Enea Edge Management for Telemetry.</para>
76
77 <note>
78 <para>Changing the InfluxDB username and password requires
79 redeploying the InfluxDB image.</para>
80 </note>
81 </listitem>
82
83 <listitem>
84 <para>Verify the installation by running the command <literal>docker
85 ps -a</literal>. The Grafana and InfluxDB containers should be
86 present and have the status <literal>Up</literal>.</para>
87 </listitem>
88 </orderedlist>
89 </section>
90 </section>
91
92 <section id="grafana_settings">
93 <title>Setting Grafana and InfluxDB parameters</title>
94
95 <para>Customizing InfluxDB and Grafana parameters can be done by selecting
96 <emphasis role="bold">System</emphasis>, then the <emphasis
97 role="bold">Configuration</emphasis> menu, accessing the <emphasis
98 role="bold">Properties</emphasis> tab, and clicking on the <emphasis
99 role="bold">Telemetry</emphasis> tab. The settings that can be changed are
100 listed in the table below:</para>
101
102 <table>
103 <title>Telemetry settings</title>
104
105 <tgroup cols="3">
106 <colspec align="left" colname="1" colwidth="1*" />
107
108 <colspec align="left" colname="2" colwidth="3*" />
109
110 <colspec align="left" colname="3" colwidth="1*" />
111
112 <tbody>
113 <row>
114 <entry><emphasis role="bold">Field name</emphasis></entry>
115
116 <entry><emphasis role="bold">Description</emphasis></entry>
117
118 <entry><emphasis role="bold">Default value</emphasis></entry>
119 </row>
120
121 <row>
122 <entry>Grafana Hostname or IP Address</entry>
123
124 <entry>The hostname or IP address where the Grafana instance is
125 installed.</entry>
126
127 <entry>no default</entry>
128 </row>
129
130 <row>
131 <entry>Grafana Port</entry>
132
133 <entry>The port Grafana uses.</entry>
134
135 <entry>3000</entry>
136 </row>
137
138 <row>
139 <entry>Grafana Dashboard</entry>
140
141 <entry>The dashboard that should be used when opening Grafana
142 using the Enea Edge Management.</entry>
143
144 <entry>host</entry>
145 </row>
146
147 <row>
148 <entry>InfluxDB Hostname or IP Address</entry>
149
150 <entry>The hostname or IP address where the InfluxDB database is
151 installed.</entry>
152
153 <entry>no default</entry>
154 </row>
155
156 <row>
157 <entry>InfluxDB Port</entry>
158
159 <entry>The port used for communication between InfluxDB and the
160 Telemetry server.</entry>
161
162 <entry>25826</entry>
163 </row>
164
165 <row>
166 <entry>InfluxDB Username</entry>
167
168 <entry>The username used for encrypting communication between
169 InfluxDB and the Telemetry server.</entry>
170
171 <entry>admin0</entry>
172 </row>
173
174 <row>
175 <entry>InfluxDB Password</entry>
176
177 <entry>The password used for encrypting communication between
178 InfluxDB and the Telemetry server.</entry>
179
180 <entry>admin</entry>
181 </row>
182 </tbody>
183 </tgroup>
184 </table>
185
186 <para>When changing any of the settings in the <emphasis
187 role="bold">Telemetry</emphasis> tab, the Enea Edge Management will inform
188 all uCPE devices of the change if they have telemetry running.</para>
189
190 <figure>
191 <title>Telemetry Properties</title>
192
193 <mediaobject>
194 <imageobject>
195 <imagedata contentwidth="615"
196 fileref="images/telemetry_settings.png" />
197 </imageobject>
198 </mediaobject>
199 </figure>
200 </section>
201
202 <section id="telemetry_start_stop">
203 <title>Starting and stopping Telemetry</title>
204
205 <para>When a uCPE Device is selected, in the <emphasis
206 role="bold">Operations</emphasis> menu, the <emphasis role="bold">Start
207 Telemetry</emphasis> and <emphasis role="bold">Stop Telemetry</emphasis>
208 options are available.</para>
209
210 <para>When starting Telemetry for a uCPE device, the Enea Edge Management
211 sends the following information about the InfluxDB:</para>
212
213 <itemizedlist>
214 <listitem>
215 <para>The IP address and hostname where InfluxDB is installed.</para>
216 </listitem>
217
218 <listitem>
219 <para>The port used for communication between InfluxDB and the
220 Telemetry server.</para>
221 </listitem>
222
223 <listitem>
224 <para>The credentials used for encrypting communication between
225 InfluxDB and the Telemetry server.</para>
226 </listitem>
227 </itemizedlist>
228
229 <para>These fields are read-only and are populated with the values already
230 set in the <emphasis role="bold">System Configuration</emphasis>. If one
231 of the fields is not set or if it does not have the desired value, modify
232 it in the <emphasis role="bold">System Configuration</emphasis>. The
233 password is sent encrypted using the Base64 scheme.</para>
234
235 <figure>
236 <title>Telemetry Start Dialog</title>
237
238 <mediaobject>
239 <imageobject>
240 <imagedata contentwidth="615" fileref="images/telemetry_start.png" />
241 </imageobject>
242 </mediaobject>
243 </figure>
244
245 <para>When the Telemetry status is changed on a uCPE device, a
246 notification is sent to the Enea Edge Management. These notifications can
247 be inspected under <emphasis role="bold">Fault</emphasis> found in the
248 <emphasis role="bold">Event</emphasis> menu.</para>
249 </section>
250
251 <section id="grafana_launch">
252 <title>Launching Grafana</title>
253
254 <para>When a uCPE Device is selected, the <emphasis
255 role="bold">Telemetry</emphasis> button is available. Pressing this button
256 will open a new window pointing to Grafana. The current uCPE device will
257 be selected in Grafana.</para>
258
259 <para>The hostname or IP Address and the port of the Grafana installation
260 can be customized by selecting <emphasis role="bold">System</emphasis>,
261 then the <emphasis role="bold">Configuration</emphasis> menu, accessing
262 the <emphasis role="bold">Properties</emphasis> tab, and clicking on the
263 <emphasis role="bold">Telemetry</emphasis> tab. The default dashboard
264 available when launching Grafana can be customized as well.</para>
265 </section>
266</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..d9784a0
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/installation_guide.xml
@@ -0,0 +1,1193 @@
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 <entry>Required for the Enea Edge Management High Availability
190 Configuration.</entry>
191 </row>
192
193 <row>
194 <entry>5701:5708</entry>
195
196 <entry>TCP</entry>
197
198 <entry>Required for the Enea Edge Management High Availability
199 Configuration.</entry>
200 </row>
201
202 <row>
203 <entry>4334</entry>
204
205 <entry>TCP</entry>
206
207 <entry>Required for Call Home.</entry>
208 </row>
209
210 <row>
211 <entry>2021:2040</entry>
212
213 <entry>TCP</entry>
214
215 <entry>Required for Call Home when connecting uCPE Devices using
216 Enea NFV Access 2.3.0 or older.</entry>
217 </row>
218 </tbody>
219 </tgroup>
220 </table>
221
222 <para>Use the following command sequence to enable the required ports
223 for deployment of the Enea Edge Management:</para>
224
225 <programlisting>sudo firewall-cmd --permanent --add-port=80/tcp
226sudo firewall-cmd --permanent --add-port=443/tcp
227sudo firewall-cmd --permanent --add-port=54327/udp
228sudo firewall-cmd --permanent --add-port=5701-5708/tcp
229sudo firewall-cmd --permanent --add-port=4334/tcp
230sudo firewall-cmd --permanent --add-port=2021-2040/tcp
231sudo firewall-cmd --reload</programlisting>
232
233 <note>
234 <para>If the Enea Edge Management host resides behind a corporate
235 port-filtering firewall, then all the aforementioned ports need to
236 also be enabled on the respective firewall. As an additional
237 requirement, port 22/TCP also needs to be enabled for reverse SSH to
238 the Enea Edge Management.</para>
239
240 <para>No enabling and no forwarding rules are necessary for ports
241 2021-2040 if using Enea Edge 2.4.0 or newer.</para>
242 </note>
243 </section>
244
245 <section id="openjdk_postgresql_config">
246 <title>Configuring OpenJDK and PostgreSQL</title>
247
248 <para>The Enea Edge Management requires a specific Java version (OpenJDK
249 11) and a PostgreSQL version to operate correctly.</para>
250
251 <para><emphasis role="bold">Installing OpenJDK</emphasis></para>
252
253 <orderedlist spacing="compact">
254 <listitem>
255 <para>Install OpenJDK 11 using the root account:</para>
256
257 <programlisting>yum install java-11-openjdk-devel</programlisting>
258 </listitem>
259
260 <listitem>
261 <para>Verify the installation:</para>
262
263 <programlisting>java -version
264openjdk version "11.0.3" 2019-04-16 LTS
265OpenJDK Run Time Environment 18.9 (build 11.0.3+7-LTS)
266OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing)</programlisting>
267
268 <note>
269 <para>If there are multiple java versions installed, switch
270 between them using the following command:</para>
271
272 <programlisting>alternatives --config java</programlisting>
273
274 <para>Optionally, the user can switch between the
275 <literal>javac</literal> versions using:</para>
276
277 <programlisting>alternatives --config javac</programlisting>
278 </note>
279 </listitem>
280
281 <listitem>
282 <para>The following system variables need to point to the OpenJDK 11
283 installation:</para>
284
285 <programlisting>export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which java)))))
286export PATH=$PATH:$JAVA_HOME/bin
287export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar</programlisting>
288
289 <note>
290 <para>In order to make these system variables persistent, the
291 commands given above should be added to a script in the
292 <literal>/etc/profile.d/</literal> folder. <emphasis
293 role="bold">Sudo</emphasis> access is needed for this
294 operation.</para>
295 </note>
296 </listitem>
297 </orderedlist>
298
299 <para>The Enea Edge Management requires a specific PostgreeSQL version.
300 This is embedded in the Enea Edge Management installation. In order to
301 avoid conflicts, any existing PostgreeSQL installation needs to be
302 uninstalled.</para>
303
304 <para><emphasis role="bold">Uninstalling PostgreSQL</emphasis></para>
305
306 <orderedlist>
307 <listitem>
308 <para>Open a terminal with administrative rights, i.e. log into a
309 bash shell with root privileges.</para>
310 </listitem>
311
312 <listitem>
313 <para>Execute the following command to check if you have a currently
314 running PostgreSQL database server:</para>
315
316 <programlisting>ps -ef | grep post</programlisting>
317 </listitem>
318
319 <listitem>
320 <para>Remove the installed PostgreSQL server (including the existing
321 postgres user):</para>
322
323 <note>
324 <para>This step is not necessary if the Enea Edge Management will
325 be using an external database (like MariaDB).</para>
326 </note>
327
328 <programlisting>yum remove postgres\*
329rm -rf /var/lib/pgsql
330rm -f /etc/postgres-reg.ini
331userdel postgres</programlisting>
332 </listitem>
333 </orderedlist>
334
335 <para>If you have multiple spindles, it is recommended to let the
336 application run off one and the database off the other. This will result
337 in optimum performance. It is also recommended that the swap disk be the
338 same as the one used for the application.</para>
339
340 <para>Assuming another spindle is used (<literal>/drive2</literal>) do
341 the following:</para>
342
343 <orderedlist>
344 <listitem>
345 <para>Create a folder which will host the database (e.g.
346 <literal>emsDatabase</literal>).</para>
347 </listitem>
348
349 <listitem>
350 <para>Create a soft-link that will point to this folder:</para>
351
352 <programlisting>ln -s /opt/ems/elementcenter/database /drive2/emsDatabase</programlisting>
353 </listitem>
354
355 <listitem>
356 <para>Follow the installation steps for the Enea Edge Management
357 available in <olink targetdoc="book_enea_nfv_access_getting_started"
358 targetptr="install_ucpe_mg">Installing the Enea Edge Management in
359 the <xi:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
360 xmlns:xi="http://www.w3.org/2001/XInclude"
361 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
362 Manual.</para>
363 </listitem>
364 </orderedlist>
365 </section>
366 </section>
367
368 <section id="ucpe_config">
369 <title>uCPE Device Configuration</title>
370
371 <section id="wan_lan_ports">
372 <title>Determining the WAN and LAN ports</title>
373
374 <para>A typical whitebox comes with multiple physical network ports,
375 ready to be used. The user must determine the purpose and allocation of
376 each port. The allocation is later aligned with the software
377 configuration within the Web-installer.</para>
378
379 <para>A common way is to allocate the left ports to WANs and the right
380 ports to LANs. At least one port must be allocated to WAN and one to
381 LAN.</para>
382 </section>
383
384 <section id="ucpe_identifier">
385 <title>Determining the Device ID</title>
386
387 <para>Each uCPE device needs a unique identifier. This identifier is
388 used to match the registration in the Enea Edge Management and the
389 offline configuration of the uCPE device during ZTP (Zero Touch
390 Provisioning).</para>
391
392 <para>Select a text string to represent the uCPE device, e.g.
393 <literal>uCPE-1</literal> or <literal>fwa-t1012vc_boston_1234</literal>.
394 It can have any length and any type of characters with the exception of
395 quotation characters (' or ") or line terminators (\n or \r) which can
396 interfere with the JSON format of the
397 <filename>install_data.json</filename> file.</para>
398 </section>
399
400 <section id="bios_config">
401 <title>Configuring the BIOS</title>
402
403 <para>The factory configuration of the BIOS may not match the
404 requirements of Enea Edge Runtime. The BIOS configuration needs to be
405 reviewed and potentially reconfigured to prepare for a successful
406 installation.</para>
407
408 <para>Access the BIOS using a serial cable between the uCPE device and
409 the laptop, to review and configure the BIOS correctly. The whitebox
410 vendor is expected to provide the right serial cable for the box. A
411 terminal emulator (such as putty) is needed on the laptop.</para>
412
413 <para>Enable the following BIOS features/configurations:</para>
414
415 <itemizedlist>
416 <listitem>
417 <para>EFI</para>
418 </listitem>
419
420 <listitem>
421 <para>Intel Virtualization Technology (VT-x)</para>
422 </listitem>
423
424 <listitem>
425 <para>Intel Virtualization Technology for Directed I/O (VT-d)</para>
426 </listitem>
427
428 <listitem>
429 <para>SR-IOV</para>
430 </listitem>
431 </itemizedlist>
432
433 <para>The boot order may also need to be modified to support
434 installation and execution of the Enea Edge Runtime on the uCPE
435 device.</para>
436
437 <para>The following boot order is recommended for a base
438 configuration:</para>
439
440 <orderedlist>
441 <listitem>
442 <para>Boot from USB</para>
443 </listitem>
444
445 <listitem>
446 <para>Boot from Disk</para>
447 </listitem>
448 </orderedlist>
449
450 <para>By arranging the above boot order there is no need for a further
451 configuration of the BIOS during installation and deployment.</para>
452 </section>
453 </section>
454
455 <section id="prep_deploy">
456 <title>Preparing the Deployment</title>
457
458 <section id="install_ucpe_mg">
459 <title>Installing the Enea Edge Management</title>
460
461 <para>The Enea Edge Management can be installed using a fresh
462 (first-time) configuration or using a backup file of a previous
463 installation, created within the Enea Edge Management GUI.</para>
464
465 <section id="fresh_ucpemg_install">
466 <title>Fresh Installation of the Enea Edge Management</title>
467
468 <para>On the CentOS 7 server open a terminal, log into a bash shell
469 with the root account and perform the following:</para>
470
471 <orderedlist>
472 <listitem>
473 <para>Extract
474 <literal>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</literal></para>
475
476 <para>The directory in which the archive has been unpacked will be
477 denoted as: <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
478 </listitem>
479
480 <listitem>
481 <para>Enter <literal>&lt;uCPEM-installdir&gt;/dist</literal>.</para>
482 </listitem>
483
484 <listitem>
485 <para>Choose the target installation folder, e.g.
486 <literal>/opt/ems</literal>. Everything will be installed under a
487 folder called <literal>/ucpemanager</literal> within the target
488 installation folder.</para>
489
490 <para>The application files will be installed in
491 <literal>/opt/ems/ucpemanager/application</literal>. The database
492 will be installed in
493 <literal>/opt/ems/ucpemanager/database</literal>.</para>
494 </listitem>
495
496 <listitem>
497 <para>Run the following interactive command:</para>
498
499 <programlisting>./install.sh /opt/ems \
500Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
501
502 <para>The default configuration values are specified in brackets.
503 If no other value is preferred and typed in, pressing
504 <literal>ENTER</literal> will keep the default values. When there
505 is an option within parentheses (i.e.Y/N), a value must be
506 specified.</para>
507
508 <note>
509 <para>The same configuration values set now will need to be
510 provided when upgrading or uninstalling the Enea Edge
511 Management.</para>
512 </note>
513
514 <itemizedlist>
515 <listitem>
516 <para>Database Configurations:</para>
517
518 <itemizedlist spacing="compact">
519 <listitem>
520 <para>Are you using the embedded PostgreSQL database?
521 [Y/N]: <literal>Y</literal>.</para>
522 </listitem>
523
524 <listitem>
525 <para>Specify the database process password
526 <literal>[postgres]:</literal></para>
527 </listitem>
528
529 <listitem>
530 <para>Specify the database ID (or name)
531 <literal>[ucpemanager]:</literal></para>
532 </listitem>
533
534 <listitem>
535 <para>Specify the database server port
536 <literal>[5432]:</literal></para>
537 </listitem>
538
539 <listitem>
540 <para>Specify a database user name
541 <literal>[postgres]:</literal></para>
542 </listitem>
543
544 <listitem>
545 <para>Specify a database password
546 <literal>[postgres]:</literal></para>
547 </listitem>
548
549 <listitem>
550 <para>Specify the database startup thread pool size
551 <literal>[1]:</literal></para>
552 </listitem>
553 </itemizedlist>
554 </listitem>
555
556 <listitem>
557 <para>Service Configurations:</para>
558
559 <itemizedlist spacing="compact">
560 <listitem>
561 <para>Specify a service username
562 [<literal>ucpemanager</literal>]:</para>
563 </listitem>
564
565 <listitem>
566 <para>Specify a service password
567 <literal>[ucpemanager</literal>]:</para>
568 </listitem>
569 </itemizedlist>
570 </listitem>
571
572 <listitem>
573 <para>High Availability Configurations:</para>
574
575 <itemizedlist spacing="compact">
576 <listitem>
577 <para>Specify the IP address of the local interface: The
578 CentOS 7 Server loopback address:
579 <literal>127.0.0.1</literal>.</para>
580 </listitem>
581
582 <listitem>
583 <para>Is this server part of a cluster? [Y/N]:
584 <literal>N</literal>.</para>
585 </listitem>
586 </itemizedlist>
587 </listitem>
588
589 <listitem>
590 <para>Heap Configuration: <literal>Please enter the new
591 Maximum Heap Size [4g]</literal>:</para>
592 </listitem>
593
594 <listitem>
595 <para>Create the self-signed certificate: <literal>Specify IP
596 or domain name:</literal></para>
597
598 <note>
599 <para>The certificate can be generated again by running the
600 <filename>createCertificate</filename> script from the
601 distribution folder.</para>
602 </note>
603 </listitem>
604 </itemizedlist>
605
606 <para>This command will:</para>
607
608 <itemizedlist spacing="compact">
609 <listitem>
610 <para>Extract the application files from the compressed
611 installation kit.</para>
612 </listitem>
613
614 <listitem>
615 <para>Install the bundled database.</para>
616 </listitem>
617
618 <listitem>
619 <para>Install the Enea Edge Management as a service with the
620 name <literal>ucpemanager</literal>.</para>
621 </listitem>
622
623 <listitem>
624 <para>Start the <literal>ucpemanager</literal> service</para>
625 </listitem>
626 </itemizedlist>
627 </listitem>
628
629 <listitem>
630 <para>Using the IPv4 address of the CentOS 7 Server in a web
631 browser, running on the laptop, log into the Enea Edge Management
632 GUI using the default username and password:
633 <literal>admin/admin</literal>.</para>
634 </listitem>
635 </orderedlist>
636
637 <note>
638 <para>The IPv4 address of the CentOS 7 Server, connected to the same
639 network as the uCPE Devices, will be used as a configuration
640 parameter when setting up the uCPE devices.</para>
641
642 <para>If the CentOS 7 Server is installed behind NAT, the IPv4
643 address used will be the public IP of the NAT device and port
644 forwarding rules must be created to ensure the uCPE device can
645 access the Enea Edge Management. For more details, please see <link
646 linkend="firewall_config">Firewall Configuration</link>.</para>
647 </note>
648 </section>
649
650 <section id="install_ucpemg_from_backup">
651 <title>Installation of the Enea Edge Management using a System
652 Back-up</title>
653
654 <para>The Enea Edge Management can be restored if a backup file has
655 been previously created.</para>
656
657 <para>A backup file can be created by accessing the <emphasis
658 role="bold">System</emphasis> menu, and clicking <emphasis
659 role="bold">System Backup</emphasis>, from the Enea Edge Management
660 GUI. The resulting zip archive will be located in the
661 <filename>/opt/ems/ucpemanager/application/backup</filename> folder
662 and will be named
663 <literal>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</literal> (e.g
664 System-Backup_Feb19_2013_2257_42.zip). Save the archive to another
665 location outside the Enea Edge Management installation folder for
666 future use.</para>
667
668 <note>
669 <para>The System Back-up file obtained from the Enea Edge Management
670 GUI (<filename>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</filename>) is
671 different from the snapshot obtained during a Enea Edge Management
672 Upgrade or Uninstall operation
673 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>) needed
674 for recovery of the Enea Edge Management. For more details, see
675 <olink targetdoc="book_enea_nfv_access_getting_started"
676 targetptr="restore_prev_ucpe_install">Restoring a previous Enea Edge
677 Management installation in the <xi:include
678 href="../../s_docbuild/olinkdb/pardoc-names.xml"
679 xmlns:xi="http://www.w3.org/2001/XInclude"
680 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
681 Manual.</para>
682 </note>
683
684 <para>To install the Enea Edge Management with the restore option
685 provide an additional argument as shown below during
686 installation:</para>
687
688 <programlisting>./install.sh \
689/opt/ems Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz \
690SystemBackup_MMMDD_YYYY_HHMM_SS.zip</programlisting>
691 </section>
692 </section>
693
694 <section id="prep_usb_ena">
695 <title>Preparing the USB stick for installation of the Enea Edge
696 Runtime</title>
697
698 <para>To install the Enea Edge Runtime, create a bootable USB stick with
699 the image you intend to install.</para>
700
701 <para>In the example below, step by step instructions are provided for
702 the CentOS 7 distribution. It's possible with the appropriate tools to
703 also use Windows OS or MacOS.</para>
704
705 <note>
706 <para>The <filename>.hddimg</filename> image is available in the
707 <filename>Enea_Edge_Runtime_Platform_
708 &lt;processor&gt;_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
709 file you downloaded with your release.</para>
710 </note>
711
712 <para><emphasis role="bold">Create a bootable USB stick
713 image</emphasis></para>
714
715 <orderedlist>
716 <listitem>
717 <para>Copy the <filename>.hddimg</filename> image file provided by
718 Enea, into the CentOS 7 server.</para>
719 </listitem>
720
721 <listitem>
722 <para>Connect the USB stick to the CentOS 7 Server and identify the
723 USB device name given by the system with
724 <literal>lsblk</literal>:</para>
725
726 <programlisting>NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
727sda 8:0 1 28.7G 0 disk
728sdb 8:0 0 111.8G 0 disk
729|-sdb1 8:1 0 111.8G 0 part</programlisting>
730 </listitem>
731
732 <listitem>
733 <para>Copy the <filename>.hddimg</filename> image onto the USB
734 stick, e.g:</para>
735
736 <programlisting>sudo dd if=./enea-nfv-access-&lt;machine&gt;.hddimg \
737of=/dev/sdb bs=4M conv=fsync</programlisting>
738
739 <para>Where
740 <filename>enea-nfv-access-&lt;machine&gt;.hddimg</filename> is the
741 <filename>.hddimg</filename> file and <literal>sdb</literal> is the
742 assigned USB device name.</para>
743 </listitem>
744 </orderedlist>
745 </section>
746
747 <section id="prep_phys_deploy">
748 <title>Preparing Physical Deployment for Installation</title>
749
750 <figure>
751 <title>Preparing for Hardware Installation</title>
752
753 <mediaobject>
754 <imageobject>
755 <imagedata contentwidth="600" fileref="images/prep_deploy.png" />
756 </imageobject>
757 </mediaobject>
758 </figure>
759
760 <para>While the uCPE device is powered off, in order to install and
761 configure the Enea Edge Runtime (using the prepared USB stick), connect
762 the laptop to a uCPE device LAN port. For this purpose, a Layer 2 switch
763 or direct cable connection can be used.</para>
764 </section>
765
766 <section id="install_ena_device">
767 <title>Installing Enea Edge - uCPE Device Installation</title>
768
769 <para>To initiate the installation of the Enea Edge Runtime do the
770 following:</para>
771
772 <orderedlist>
773 <listitem>
774 <para>Plug the USB stick into the uCPE device.</para>
775 </listitem>
776
777 <listitem>
778 <para>Power up the uCPE device and boot the USB stick.</para>
779 </listitem>
780
781 <listitem>
782 <para>The Web-installer application will start automatically and can
783 be accessed in a web browser on the laptop at
784 <literal>http://172.16.1.1</literal> (port 80).</para>
785 </listitem>
786
787 <listitem>
788 <para>On the <emphasis role="bold">Requirements</emphasis> page of
789 the Web-installer, the user must confirm the current state of
790 installation prerequisites is inline with the desired state:</para>
791
792 <itemizedlist>
793 <listitem>
794 <para>Requirements table. Minimum values apply to the
795 installation process only. For runtime operations, additional
796 resources should be available depending on the specific
797 workload. Requirements are color coded (green when met, red when
798 mandatory and not met, orange when optional and not met). The
799 Requirements table has the following fields:</para>
800
801 <itemizedlist spacing="compact">
802 <listitem>
803 <para>Disk size (mandatory). 2GB or more are required for
804 the installation.</para>
805 </listitem>
806
807 <listitem>
808 <para>CPU cores (mandatory). 2 cores or more are required
809 for the installation.</para>
810 </listitem>
811
812 <listitem>
813 <para>RAM (mandatory). 2GB or more are required for the
814 installation.</para>
815 </listitem>
816
817 <listitem>
818 <para>VT-x (mandatory). Intel Virtualization Technology must
819 be enabled.</para>
820 </listitem>
821
822 <listitem>
823 <para>VT-d (optional, recommended). Intel Virtualization
824 Technology for Directed I/O should be enabled.</para>
825 </listitem>
826
827 <listitem>
828 <para>IOMMU Group separation (optional). If the hardware
829 does not support IOMMU Group separation, there are certain
830 limitations regarding how the <literal>vfio-pci</literal>
831 driver can be used. For more details, see the <olink
832 targetdoc="book_enea_nfv_access_release_info"
833 targetptr="bugs-limitations">Known Issues and Limitations in
834 this Release in the <xi:include
835 href="../../s_docbuild/olinkdb/pardoc-names.xml"
836 xmlns:xi="http://www.w3.org/2001/XInclude"
837 xpointer="element(book_enea_nfv_access_release_info/1)" /></olink>
838 Manual.</para>
839 </listitem>
840 </itemizedlist>
841 </listitem>
842
843 <listitem>
844 <para>Force installation checkbox. When enabled, the
845 installation can be performed even if some of the mandatory
846 requirements are not met or if non-fatal problems are detected
847 during the process.</para>
848 </listitem>
849 </itemizedlist>
850 </listitem>
851
852 <listitem>
853 <para>On the Enea <emphasis role="bold">Edge Management
854 settings</emphasis> page of the Web-installer, the user must fill
855 in:</para>
856
857 <itemizedlist>
858 <listitem>
859 <para>The static Enea Edge Management IP Address or FQDN. This can be
860 either:</para>
861
862 <itemizedlist spacing="compact">
863 <listitem>
864 <para>The IP address of the Enea Edge Management host
865 machine, if the device can directly access it.</para>
866 </listitem>
867
868 <listitem>
869 <para>The IP address of the NAT device, if the Enea Edge
870 Management host is located behind a NAT. For more details,
871 please see <link linkend="firewall_config">Firewall
872 Configuration</link>.</para>
873 </listitem>
874
875 <listitem>
876 <para>The Fully Qualified Domain Name (FQDN) of the Enea
877 uCPE Manager host machine.</para>
878 </listitem>
879 </itemizedlist>
880 </listitem>
881
882 <listitem>
883 <para>The unique identifier of the uCPE device (called
884 "DeviceId" in this guide).</para>
885 </listitem>
886
887 <listitem>
888 <para>Customer Tags. They are used for Zero Touch Provisioning
889 (ZTP) and can be left empty for a base configuration. What can
890 be entered here (if needed), are the tag(s) specified when
891 creating an offline configuration in the Enea Edge Management. A
892 later addition of customer tags can only be done by reinstalling
893 the uCPE devices.</para>
894 </listitem>
895 </itemizedlist>
896 </listitem>
897
898 <listitem>
899 <para>Connect the WAN cable to the uCPE device (see Figure 2). This
900 will be used as the uCPE management network interface, as described
901 below.</para>
902 </listitem>
903
904 <listitem>
905 <para>On the <emphasis role="bold">Network Setup</emphasis> page of
906 the Web-installer, the user must do the following:</para>
907
908 <itemizedlist>
909 <listitem>
910 <para>Select a WAN interface to use as the management network
911 interface. This interface is used by the Enea Edge Management to
912 communicate with the uCPE device.</para>
913 </listitem>
914
915 <listitem>
916 <para>Plug-in additional WAN interfaces (if applicable) and
917 provide their Layer 3 configuration.</para>
918 </listitem>
919 </itemizedlist>
920 </listitem>
921 </orderedlist>
922
923 <para>When the user has completed the configuration steps in the
924 Web-installer, Enea Edge Runtime is installed on the hard drive. At this
925 stage, the user should remove the USB stick and the LAN cable, and
926 shutdown the uCPE device. It will be started after necessary
927 configurations are done in the Enea Edge Management, as described
928 below.</para>
929
930 <note>
931 <para>If errors are detected during installation, full logs will be
932 available on the last page of the Web-installer. Please contact Enea
933 for log analysis. The system is not expected to be usable if errors are
934 reported during installation.</para>
935
936 <para>If the USB stick was booted in UEFI mode, a UEFI boot entry is
937 automatically created and the system will start booting from the hard
938 drive without further user configuration.</para>
939 </note>
940 </section>
941
942 <section id="prep_phys_exec">
943 <title>Preparing Physical Deployment for Execution</title>
944
945 <figure>
946 <title>Preparing for Deployment Execution</title>
947
948 <mediaobject>
949 <imageobject>
950 <imagedata contentwidth="600" fileref="images/prep_execution.png" />
951 </imageobject>
952 </mediaobject>
953 </figure>
954
955 <para>The following network configuration is needed for managing the
956 uCPE device and service deployment:</para>
957
958 <itemizedlist>
959 <listitem>
960 <para>Network connection between the server running the Enea Edge
961 Management and the laptop.</para>
962 </listitem>
963
964 <listitem>
965 <para>Network connection between the server running the Enea Edge
966 Management and the uCPE device.</para>
967 </listitem>
968 </itemizedlist>
969 </section>
970 </section>
971
972 <section id="mg_ucpe_devices">
973 <title>Management of uCPE Devices</title>
974
975 <para>When the installation is complete the uCPE device can be managed in
976 the Enea Edge Management.</para>
977
978 <section id="add_offline_config">
979 <title>Add a default Offline Configuration</title>
980
981 <para>Zero Touch Provisioning is always turned on when a uCPE device
982 connects to the Enea Edge Management. To enable it in the Enea Edge
983 Management, an offline configuration needs to be registered for Day-0
984 configuration.</para>
985
986 <note>
987 <para>Day-0 configuration is a software lifecycle term referring to
988 early configurations used to put the uCPE device in an active state.
989 Day-1 Configurations are applied after Day-0 and set the uCPE device
990 and its service in an active state. Day-2 Configurations are live
991 configurations on the uCPE device and its service, applied after they
992 have been activated.</para>
993 </note>
994
995 <para>The offline configuration consists of data and parameters that are
996 meant to be automatically set when a uCPE device connects to the Enea
997 Edge Management for the first time. The configuration is typically
998 focused on setting up the network management of the uCPE device, e.g.
999 configuring network interfaces, WAN and LAN networking and service
1000 chains.</para>
1001
1002 <para>For this base configuration, the offline configuration will be
1003 left blank. The blank offline configuration can be filled with
1004 user-specific values and data once the service is created, which is done
1005 after the installation is complete.</para>
1006
1007 <note>
1008 <para>If the offline configuration is not configured, an alarm will be
1009 raised: <literal>Day-0 Config:ZTP:Major</literal> when the uCPE device
1010 tries to connect to the Enea Edge Management, informing the user that
1011 the ZTP setup failed for the uCPE device.</para>
1012 </note>
1013
1014 <para><emphasis role="bold">To create an offline
1015 configuration</emphasis><orderedlist>
1016 <listitem>
1017 <para>In a browser access the Enea Edge Management, open <emphasis
1018 role="bold">Applications</emphasis> and select <emphasis
1019 role="bold">Offline Config</emphasis>.</para>
1020 </listitem>
1021
1022 <listitem>
1023 <para>Create a new offline configuration in the GUI by selecting
1024 the <emphasis role="bold">Add</emphasis> button and filling in the
1025 mandatory fields: <literal>name</literal>,
1026 <literal>deviceVersion</literal> and
1027 <literal>deviceId</literal>.</para>
1028
1029 <para>The name is user defined and can be set to any unique text
1030 string identifying the configuration. The
1031 <literal>deviceVersion</literal> must match the Enea Edge Runtime
1032 version of the uCPE device and the <literal>deviceId</literal>
1033 must be the previously set identifier of the uCPE device
1034 (DeviceId).</para>
1035 </listitem>
1036 </orderedlist></para>
1037 </section>
1038
1039 <section id="add_ucpe_mg">
1040 <title>Add a uCPE device to the Management System</title>
1041
1042 <para>In order to enroll a uCPE device in the management system and
1043 establish a management connection, the user will add uCPE device
1044 information in the Enea Edge Management. This is accomplished by going
1045 to <emphasis role="bold">Devices</emphasis>, selecting <emphasis
1046 role="bold">Manage</emphasis> and then clicking the <emphasis
1047 role="bold">Add</emphasis> button.</para>
1048
1049 <para>The relevant parameters are:</para>
1050
1051 <itemizedlist>
1052 <listitem>
1053 <para><emphasis role="bold">Type.</emphasis> The type of device to
1054 be added, i.e Enea universal CPE.</para>
1055 </listitem>
1056
1057 <listitem>
1058 <para><emphasis role="bold">Name.</emphasis> The name by which the
1059 uCPE device is referred to in the Enea Edge Management.
1060 (Mandatory).</para>
1061 </listitem>
1062
1063 <listitem>
1064 <para><emphasis role="bold">SSH Port.</emphasis> The NETCONF Port
1065 used for communications. Default is set to 830.</para>
1066 </listitem>
1067
1068 <listitem>
1069 <para><emphasis role="bold">SSH User Name.</emphasis> The user name
1070 for SSH connectivity. Default user is root.</para>
1071 </listitem>
1072
1073 <listitem>
1074 <para><emphasis role="bold">SSH Password.</emphasis> Leave this
1075 blank.</para>
1076 </listitem>
1077
1078 <listitem>
1079 <para><emphasis role="bold">Device Calls Home.</emphasis> This
1080 checkbox indicates the direction of uCPE device communications. For
1081 a base configuration, leave this flag unchecked.</para>
1082 </listitem>
1083
1084 <listitem>
1085 <para><emphasis role="bold">Device ID.</emphasis> The unique
1086 identifier of the uCPE device. (Mandatory).</para>
1087 </listitem>
1088 </itemizedlist>
1089
1090 <para>For more details concerning Device Calls Home, please see <olink
1091 targetdoc="book_enea_nfv_access_getting_started"
1092 targetptr="device_callhome_nat">Device Call Home Connection for
1093 Deployment behind NAT in the <xi:include
1094 href="../../s_docbuild/olinkdb/pardoc-names.xml"
1095 xmlns:xi="http://www.w3.org/2001/XInclude"
1096 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
1097 Manual.</para>
1098 </section>
1099
1100 <section id="boot_device_add_map">
1101 <title>Booting the uCPE device and adding it to the Map</title>
1102
1103 <para>When connectivity is established with the Enea Edge Management and
1104 a uCPE device is already registered with a matching <literal>Device
1105 ID</literal>, the installation is complete, and the connection is
1106 established.</para>
1107
1108 <para>When a uCPE device is registered it can be manually added to the
1109 map for overview. <emphasis role="bold">Right-click</emphasis> on the
1110 map and select <emphasis role="bold">Place Device</emphasis> to put the
1111 uCPE device on the map.</para>
1112
1113 <para>In case of management connection failure (e.g. due to a
1114 misconfiguration), the uCPE device status will be seen as RED
1115 (disconnected) in the Enea Edge Management. The uCPE device
1116 configuration can be corrected by removing the WAN cable(s),
1117 reconnecting the laptop to the LAN interface of the uCPE device and
1118 rebooting it. At this point, the Web-installer can be accessed from the
1119 laptop as described in <olink
1120 targetdoc="book_enea_nfv_access_getting_started"
1121 targetptr="install_ena_device">Installing Enea Edge - uCPE Device
1122 installation in the <xi:include
1123 href="../../s_docbuild/olinkdb/pardoc-names.xml"
1124 xmlns:xi="http://www.w3.org/2001/XInclude"
1125 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
1126 Manual.</para>
1127 </section>
1128 </section>
1129
1130 <section id="ucpe_monitor">
1131 <title>uCPE Device Monitorization and Control</title>
1132
1133 <para>Once the uCPE device is connected to the Enea Edge Management, it is
1134 ready for central management. Two important functions available in the
1135 Enea Edge Management GUI are alarm checking and resource
1136 allocation.</para>
1137
1138 <section id="check_alarms">
1139 <title>Checking Alarms</title>
1140
1141 <para>The Enea Edge Management dashboard presents alarms in a specific
1142 window on the front page.</para>
1143
1144 <para>An alarm can be easily triggered by disconnecting and reconnecting
1145 the WAN ethernet cable from the uCPE device. The management system will
1146 detect the broken link and raise an alarm: <literal>Device
1147 Disconnected::Critical</literal>.</para>
1148
1149 <para>A separate Alarm Management window can be accessed from the Enea
1150 Edge Management menu for in-depth access and programming of Alarms and
1151 Events.</para>
1152 </section>
1153
1154 <section id="ck_resource_alloc">
1155 <title>Checking uCPE device Resource Allocation</title>
1156
1157 <para>When the uCPE device is connected to the Enea Edge Management it
1158 is of interest to check the amount of hardware resources in use.</para>
1159
1160 <para>To check CPU, RAM and disk utilization simply select the uCPE
1161 device and go to the <emphasis role="bold">Virtual Machines</emphasis>
1162 tab in the map view. The same view will show active VNFs running on the
1163 uCPE device once instantiated.</para>
1164 </section>
1165
1166 <section id="access_device_cli">
1167 <title>Accessing the uCPE device CLI</title>
1168
1169 <para>As a final check to make sure the uCPE device was installed and
1170 configured correctly, access the uCPE device Linux CLI by selecting the
1171 uCPE device on the map and using the <emphasis role="bold">SSH
1172 button</emphasis> from the panel. A new window will appear for CLI
1173 access. The default user and password are <literal>root</literal> and
1174 blank, respectively.</para>
1175
1176 <para>This is a pure Linux CLI providing access to standard Linux CLI
1177 commands. The CLI is a central feature for running custom
1178 scripting.</para>
1179
1180 <note>
1181 <para>In case the uCPE device was installed behind a NAT device, the
1182 reverse SSH connection will be used. For more details, please see
1183 <olink targetdoc="book_enea_nfv_access_getting_started"
1184 targetptr="device_callhome_nat">Device Call Home Connection for
1185 deployment behind NAT in the <xi:include
1186 href="../../s_docbuild/olinkdb/pardoc-names.xml"
1187 xmlns:xi="http://www.w3.org/2001/XInclude"
1188 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
1189 Manual.</para>
1190 </note>
1191 </section>
1192 </section>
1193</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..4dec1e1
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/introduction.xml
@@ -0,0 +1,264 @@
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 <para>In addition, Enea Edge includes a framework for
48 automation and testing. More information can be found in
49 <xi:include href="../../s_docbuild/olinkdb/pardoc-common.xml"
50 xmlns:xi="http://www.w3.org/2001/XInclude"
51 xpointer="element(book_enea_nfv_access_auto_fw_user_guide/1)" />.</para>
52
53 <para>Details concerning release content, including documentation
54 structure, are provided in the <xi:include
55 href="../../s_docbuild/olinkdb/pardoc-common.xml"
56 xmlns:xi="http://www.w3.org/2001/XInclude"
57 xpointer="element(book_enea_nfv_access_release_info/1)" /> manual included
58 with your release.</para>
59
60 <section id="nfv_access">
61 <title>Enea Edge Runtime</title>
62
63 <para>Enea Edge Runtime is a lightweight,
64 multi-architecture virtualization platform built on de-facto standards
65 in an SDN/NFV ecosystem. It is designed for a high networking
66 performance with minimal hardware footprint, by only providing relevant
67 functionalties and technologies.</para>
68
69 <para>Virtualization methods include Virtual Machines (KVM / QEMU) and
70 container(s) (Docker). High networking throughput and low latency are
71 ensured by accelerated data plane relying on technologies like DPDK,
72 OVS-DPDK and SR-IOV/PCI-Passthrough. Key functionalities, such as
73 platform software management, virtualized networking, VNFs life-cycle
74 management and FCAPS are provided through the YANG-modelled NETCONF
75 protocol.</para>
76
77 <figure>
78 <title>VNF Space</title>
79
80 <mediaobject>
81 <imageobject>
82 <imagedata align="center" contentwidth="600"
83 fileref="images/vnf_space.png" />
84 </imageobject>
85 </mediaobject>
86 </figure>
87 </section>
88
89 <section id="ucpe_manager">
90 <title>Enea Edge Management</title>
91
92 <para>The Enea Edge Management is centralized control system providing
93 uCPEs domain management capabilities through a GUI and REST API. It can
94 be deployed on a host or a virtual machine running 64-bit CentOS 7 on an
95 x86 platform. The Enea Edge Management uses a southbound NETCONF protocol
96 to connect and manage uCPE devices.</para>
97
98 <para>The Enea Edge Management provides the following key features:</para>
99
100 <itemizedlist>
101 <listitem>
102 <para>Enea Edge Runtime Software Management</para>
103 </listitem>
104
105 <listitem>
106 <para>VNF Onboarding</para>
107 </listitem>
108
109 <listitem>
110 <para>VNF Management</para>
111 </listitem>
112
113 <listitem>
114 <para>FCAPS</para>
115 </listitem>
116
117 <listitem>
118 <para>Zero Touch Provisioning</para>
119 </listitem>
120
121 <listitem>
122 <para>Alarms / Events management and monitoring</para>
123 </listitem>
124 </itemizedlist>
125 </section>
126 </section>
127
128 <section id="def_and_acr">
129 <title>Definitions and Acronyms</title>
130
131 <section id="definitions">
132 <title>Definitions</title>
133
134 <table>
135 <title>Definitions</title>
136
137 <tgroup cols="2">
138 <colspec align="left" colname="1" colwidth="1*" />
139
140 <colspec align="left" colname="2" colwidth="3*" />
141
142 <tbody>
143 <row>
144 <entry>Enea Edge</entry>
145
146 <entry>The Enea Edge Runtime and the Enea Edge
147 Management.</entry>
148 </row>
149
150 <row>
151 <entry>Enea Edge Runtime</entry>
152
153 <entry>A lightweight, multi-architecture virtualization
154 platform, supporting Virtual Machines.</entry>
155 </row>
156
157 <row>
158 <entry>Enea Edge Management</entry>
159
160 <entry>Enea Universal Customer Premises Equipment
161 Manager.</entry>
162 </row>
163
164 <row>
165 <entry>uCPE device</entry>
166
167 <entry>A whitebox running the Enea Edge
168 Runtime.</entry>
169 </row>
170 </tbody>
171 </tgroup>
172 </table>
173 </section>
174
175 <section id="acronyms">
176 <title>Acronyms</title>
177
178 <table>
179 <title>Acronyms</title>
180
181 <tgroup cols="2">
182 <colspec align="left" colname="1" colwidth="1*" />
183
184 <colspec align="left" colname="2" colwidth="3*" />
185
186 <tbody>
187 <row>
188 <entry>API</entry>
189
190 <entry>Application Programming Interface.</entry>
191 </row>
192
193 <row>
194 <entry>DPDK</entry>
195
196 <entry>Data Plane Development Kit.</entry>
197 </row>
198
199 <row>
200 <entry>EFI</entry>
201
202 <entry>Extensible Firmware Interface.</entry>
203 </row>
204
205 <row>
206 <entry>FCAPS</entry>
207
208 <entry>Fault-management, Configuration, Accounting, Performance
209 and Security.</entry>
210 </row>
211
212 <row>
213 <entry>NETCONF</entry>
214
215 <entry>Network Configuration Protocol.</entry>
216 </row>
217
218 <row>
219 <entry>NFV</entry>
220
221 <entry>Network Functions Virtualization.</entry>
222 </row>
223
224 <row>
225 <entry>OVS</entry>
226
227 <entry>Open vSwitch.</entry>
228 </row>
229
230 <row>
231 <entry>UEFI</entry>
232
233 <entry>Unified Extensible Firmware Interface.</entry>
234 </row>
235
236 <row>
237 <entry>SR-IOV</entry>
238
239 <entry>Single Root Input/Output Virtualization.</entry>
240 </row>
241
242 <row>
243 <entry>PCI</entry>
244
245 <entry>Peripheral Component Interconnect.</entry>
246 </row>
247
248 <row>
249 <entry>REST</entry>
250
251 <entry>Representational State Transfer.</entry>
252 </row>
253
254 <row>
255 <entry>VNF</entry>
256
257 <entry>Virtual Network Function.</entry>
258 </row>
259 </tbody>
260 </tgroup>
261 </table>
262 </section>
263 </section>
264</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..641775d
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/upgrade_ena.xml
@@ -0,0 +1,588 @@
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 <para>For an example on how to upgrade an Enea Edge Management installation
84 in a High Availability setup, consult <olink
85 targetdoc="book_enea_nfv_access_getting_started"
86 targetptr="ha_upgrade">Upgrading a High Availability Deployment in the
87 <ns:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
88 xmlns:ns="http://www.w3.org/2001/XInclude"
89 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
90 Manual.</para>
91
92 <section id="restore_prev_ucpe_install">
93 <title>Restoring a previous Enea Edge Management Installation</title>
94
95 <para><emphasis role="bold">How to restore a previous Enea Edge
96 Management installation</emphasis></para>
97
98 <orderedlist>
99 <listitem>
100 <para>Extract
101 <filename>Enea_Edge_Management_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename></para>
102 </listitem>
103
104 <listitem>
105 <para>The directory in which the archive has been unpacked will be
106 denoted as <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
107 </listitem>
108
109 <listitem>
110 <para>Copy the snapshot file
111 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>)
112 created during a previous Enea Edge Management Upgrade or Enea Edge
113 Management Uninstall Operation into the
114 <literal>&lt;uCPEM-installdir&gt;</literal> directory.</para>
115 </listitem>
116
117 <listitem>
118 <para>Enter <literal>&lt;uCPEM-installdir&gt;/dist</literal>.</para>
119 </listitem>
120
121 <listitem>
122 <para>Run the following command with the root user and change
123 <literal>/opt/ems</literal> to the correct location of the Enea Edge
124 Management installation:</para>
125
126 <programlisting>./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz</programlisting>
127 </listitem>
128 </orderedlist>
129
130 <para>Running this command will:</para>
131
132 <itemizedlist>
133 <listitem>
134 <para>Remove any vestiges of the existing
135 <literal>ucpemanager</literal> service, if they exist.</para>
136 </listitem>
137
138 <listitem>
139 <para>Reinstall the Enea Edge Management application on the
140 specified target location, restoring the data in the database and
141 files in the process.</para>
142 </listitem>
143 </itemizedlist>
144
145 <para>The <literal>ucpemanager</literal> service will then start with
146 the older version now running on the system.</para>
147 </section>
148
149 <section id="uninstall_ucpem_install">
150 <title>Uninstalling an existing Enea Edge Management
151 Installation</title>
152
153 <para><emphasis role="bold">How to uninstall an existing Enea Edge
154 Management installation</emphasis></para>
155
156 <orderedlist>
157 <listitem>
158 <para>Navigate to the folder where the Enea Edge Management is
159 installed: <filename>&lt;uCPEM-installdir&gt;</filename>.</para>
160 </listitem>
161
162 <listitem>
163 <para>Run the following command with the root user and change
164 <literal>/opt/ems</literal> to the correct location of the Enea Edge
165 Management installation:</para>
166
167 <programlisting>./uninstall.sh /opt/ems</programlisting>
168 </listitem>
169 </orderedlist>
170
171 <para>Running this command will:</para>
172
173 <itemizedlist>
174 <listitem>
175 <para>Stop the currently running <literal>ucpemanager</literal>
176 service.</para>
177 </listitem>
178
179 <listitem>
180 <para>Create a compressed file of the <literal>ucpemanager</literal>
181 application folder:
182 <filename>ucpemanager-Back-up-YYYYddMMHHmm.tar.gz</filename>, which
183 contains a snapshot of the existing installation and functions as a
184 restore point.</para>
185
186 <note>
187 <para>The snapshot file created during the uninstall can be used
188 for restoring Enea Edge Management.</para>
189 </note>
190 </listitem>
191
192 <listitem>
193 <para>Uninstall the <literal>ucpemanager</literal> service, so that
194 it will not start up on reboot.</para>
195 </listitem>
196
197 <listitem>
198 <para>Uninstall the database service.</para>
199 </listitem>
200
201 <listitem>
202 <para>Completely remove the contents of the application and database
203 folders.</para>
204 </listitem>
205 </itemizedlist>
206
207 <para>After these steps, the Enea Edge Management is completely removed
208 from the system.</para>
209 </section>
210 </section>
211
212 <section id="upgrade_devices">
213 <title>uCPE device Upgrades</title>
214
215 <para>A uCPE device can be upgraded using the Enea Edge Management
216 GUI.</para>
217
218 <section id="device_up_process">
219 <title>The uCPE device Upgrade Process</title>
220
221 <para>The Device Upgrade/Install option performs the following
222 operations to the uCPE device:</para>
223
224 <orderedlist>
225 <listitem>
226 <para><emphasis role="bold">Prepare for upgrade.</emphasis> This
227 stage prepares the files needed for an upgrade.</para>
228 </listitem>
229
230 <listitem>
231 <para><emphasis role="bold">Install file on device.</emphasis> This
232 stage copies the file to the uCPE device.</para>
233 </listitem>
234
235 <listitem>
236 <para><emphasis role="bold">Upgrade Device.</emphasis> This stage
237 upgrades the uCPE device to a newer version.</para>
238 </listitem>
239 </orderedlist>
240
241 <note>
242 <para>Upgrading from Enea NFV Access 2.3.0 is not possible when using
243 the Enea uCPE Manager in HTTPS mode. Either switch to HTTP by accessing
244 <emphasis role="bold">System</emphasis>, <emphasis
245 role="bold">Configuration</emphasis>, <emphasis role="bold">Web
246 Access</emphasis> and checking the <emphasis role="bold">Enable
247 HTTP</emphasis> box, or installing it manually.</para>
248 </note>
249 </section>
250
251 <section id="mg_upgrade">
252 <title>Managing the uCPE device Upgrade</title>
253
254 <para>Before an installation or upgrade can be completed, certain
255 configuration data must be set. Files also need to be uploaded to the
256 Device Upgrade image repository in order to be uploaded to the
257 device.</para>
258
259 <para>Launch the Device Upgrade management console by selecting
260 <emphasis role="bold">Devices</emphasis> and then the <emphasis
261 role="bold">Upgrade</emphasis> button from the top tool-bar. The console
262 will contain the following tabs:</para>
263
264 <itemizedlist>
265 <listitem>
266 <para><emphasis role="bold">Image Library</emphasis>. To add/delete
267 an image.</para>
268 </listitem>
269
270 <listitem>
271 <para><emphasis role="bold">Upgrade Operations</emphasis>. See
272 upgrades that are currently running, cancel any upgrades in
273 progress, or start a uCPE device upgrade.</para>
274 </listitem>
275
276 <listitem>
277 <para><emphasis role="bold">Configuration</emphasis>. Upgrade
278 configuration parameters.</para>
279 </listitem>
280 </itemizedlist>
281
282 <note>
283 <para>The uCPE Device upgrade is done with image files of the type
284 <literal>rootfs.ostree.tar.bz2</literal>, which are available in the
285 <filename>Enea_Edge_Runtime_&lt;processor&gt;_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
286 file you downloaded with your release.</para>
287 </note>
288
289 <section id="image_lib">
290 <title>Image Library</title>
291
292 <para><emphasis role="bold">Adding an image to the image
293 repository/library</emphasis><orderedlist>
294 <listitem>
295 <para>Select <emphasis role="bold">Devices</emphasis> and then
296 the <emphasis role="bold">Upgrade</emphasis> button.</para>
297 </listitem>
298
299 <listitem>
300 <para>Select <emphasis role="bold">Add</emphasis> from the
301 <emphasis role="bold">Image Library</emphasis> tab to add a new
302 image file.</para>
303 </listitem>
304
305 <listitem>
306 <para>Select <emphasis role="bold">Choose File</emphasis> to
307 provide the path to the image file (must be of type
308 <literal>rootfs.os-tree.tar.bz2</literal>).</para>
309 </listitem>
310
311 <listitem>
312 <para>Select the target hardware platform corresponding to the
313 image being uploaded (<literal>xeon-d</literal> or
314 <literal>atom-c3000</literal>).</para>
315 </listitem>
316
317 <listitem>
318 <para>Click <emphasis role="bold">Send</emphasis> to upload the
319 image to the image repository.</para>
320 </listitem>
321 </orderedlist></para>
322
323 <para><emphasis role="bold">Deleting an image from the image
324 repository</emphasis></para>
325
326 <orderedlist>
327 <listitem>
328 <para>Select <emphasis role="bold">Devices</emphasis> and then the
329 <emphasis role="bold">Upgrade</emphasis> button.</para>
330 </listitem>
331
332 <listitem>
333 <para>Select the image you want to delete from the <emphasis
334 role="bold">Image Library</emphasis> tab and then click <emphasis
335 role="bold">Delete</emphasis>.</para>
336 </listitem>
337 </orderedlist>
338 </section>
339
340 <section id="upgrade_options">
341 <title>Upgrade Operations</title>
342
343 <para>The <emphasis role="bold">Upgrade Operations</emphasis> tab
344 allows a user to manage uCPE device upgrades in the system. It allows
345 the user to see all the upgrades that are currently in progress, as
346 well as listing the completed ones. If an upgrade succeeds or fails,
347 then a row will be added to the completed upgrades table. If one
348 fails, the failure message will be visible in the table.</para>
349
350 <note>
351 <para>The list of completed upgrade tasks resides in the cache
352 memory and will not persist across reboots of the server.</para>
353 </note>
354
355 <para><emphasis role="bold">How to Install/Upgrade a device
356 immediately or schedule the process for later</emphasis><orderedlist>
357 <listitem>
358 <para>Select <emphasis role="bold">Devices</emphasis> and then
359 the <emphasis role="bold">Upgrade</emphasis> button.</para>
360 </listitem>
361
362 <listitem>
363 <para>Select <emphasis role="bold">Upgrade Devices</emphasis>
364 from the <emphasis role="bold">Upgrade Operations</emphasis>
365 tab. This will launch a <literal>Multi Device Install
366 Image</literal> screen that will allow the user to install and
367 upgrade more than one uCPE device at a time or upgrade
368 later.</para>
369 </listitem>
370 </orderedlist></para>
371
372 <para>The configurable parameters are:</para>
373
374 <itemizedlist>
375 <listitem>
376 <para><literal>Scheduling</literal>. Click this checkbox if the
377 upgrade will be done later. Schedule the day, hour and minute for
378 when to run the upgrade.</para>
379
380 <note>
381 <para>The hour represents the local Enea Edge Management server
382 hour.</para>
383 </note>
384 </listitem>
385
386 <listitem>
387 <para><literal>Description</literal>. An optional description of
388 the operation. It is recommended to add a description so that
389 different upgrades happening simultaneously can be
390 distinguished.</para>
391 </listitem>
392
393 <listitem>
394 <para><literal>Image File</literal>. Click on <emphasis
395 role="bold">Choose Image File</emphasis> to select the image
396 file.</para>
397 </listitem>
398
399 <listitem>
400 <para><literal>Devices</literal>. The list of uCPE Devices that
401 can accept an image file is populated when the image file is
402 chosen.</para>
403
404 <para>Mark the uCPE devices that you wish to upgrade and press the
405 <emphasis role="bold">&gt;</emphasis> button to move the uCPE
406 devices to the right side of the selector. Those chosen form the
407 list of uCPE devices that will be upgraded.</para>
408 </listitem>
409
410 <listitem>
411 <para><literal>Upgrade Operation</literal>. The available options
412 are:</para>
413
414 <itemizedlist>
415 <listitem>
416 <para><literal>Install and Activate</literal>. This will do an
417 image installation as well as an upgrade.</para>
418 </listitem>
419
420 <listitem>
421 <para><literal>Install Only</literal>. This will do an image
422 installation only. The image is copied to the uCPE device, and
423 an upgrade will be done later either at a scheduled time or
424 when the option <literal>Activate Only</literal> is
425 selected.</para>
426 </listitem>
427
428 <listitem>
429 <para><literal>Activate Only</literal>. This will activate an
430 already installed image on the uCPE device.</para>
431 </listitem>
432 </itemizedlist>
433 </listitem>
434
435 <listitem>
436 <para>To start the upgrade, click <emphasis
437 role="bold">ok</emphasis>.</para>
438 </listitem>
439 </itemizedlist>
440
441 <note>
442 <para>When the uCPE device activates the upgrade, it will be
443 rebooted automatically.</para>
444 </note>
445 </section>
446
447 <section id="releases_installed">
448 <title>Releases installed on a uCPE device</title>
449
450 <para>The installed releases on a uCPE device can be viewed by
451 selecting the uCPE device first, then from the top toolbar selecting
452 <emphasis role="bold">Configuration</emphasis> and then the <emphasis
453 role="bold">Upgrade</emphasis> button.</para>
454
455 <para>The installed releases on the uCPE device, the release status,
456 release state, <literal>commit-id</literal> and release version will
457 be listed in a table.</para>
458 </section>
459
460 <section id="upgrade_status">
461 <title>uCPE device Upgrade Status</title>
462
463 <para>The status of the installation and upgrade can be viewed in the
464 <emphasis role="bold">Upgrade Operations</emphasis> tab. Ongoing or
465 scheduled upgrade operations can be viewed or cancelled.</para>
466
467 <para><emphasis role="bold">To view the status of an installation or
468 upgrade operations</emphasis></para>
469
470 <orderedlist>
471 <listitem>
472 <para>Select <emphasis role="bold">Devices</emphasis> and then the
473 <emphasis role="bold">Upgrade</emphasis> button.</para>
474 </listitem>
475
476 <listitem>
477 <para>Select <emphasis role="bold">Upgrade Operations</emphasis>.
478 The ongoing operations are listed at the top and a history of
479 failed or successful operations are listed at the bottom.</para>
480 </listitem>
481
482 <listitem>
483 <para>Select an <emphasis role="bold">Active</emphasis> or
484 <emphasis role="bold">Completed Upgrade Operation</emphasis> and
485 then the <emphasis role="bold">Device Status</emphasis> button to
486 see detailed information regarding the upgrade operation,
487 including the uCPE devices involved and information per uCPE
488 device.</para>
489 </listitem>
490 </orderedlist>
491
492 <para><emphasis role="bold">To cancel an upgrade
493 operation</emphasis></para>
494
495 <orderedlist>
496 <listitem>
497 <para>Select <emphasis role="bold">Devices</emphasis>, then the
498 <emphasis role="bold">Upgrade</emphasis> button and choose
499 <emphasis role="bold">Upgrade Operations</emphasis>.</para>
500 </listitem>
501
502 <listitem>
503 <para>Select an operation from the list and choose <emphasis
504 role="bold">Cancel Upgrade</emphasis> and <emphasis
505 role="bold">Confirm</emphasis>. The operation will then be deleted
506 from the list.</para>
507 </listitem>
508 </orderedlist>
509 </section>
510
511 <section id="config">
512 <title>Configuration</title>
513
514 <note>
515 <para>The default values present in the configuration of each uCPE
516 device are recommended for use. Modifying them is for an <emphasis
517 role="bold">Advanced User</emphasis> only.</para>
518 </note>
519
520 <para><emphasis role="bold">How to Configure the uCPE device
521 Upgrade</emphasis><orderedlist>
522 <listitem>
523 <para>Select <emphasis role="bold">Devices</emphasis> and then
524 the <emphasis role="bold">Upgrade</emphasis> button.</para>
525 </listitem>
526
527 <listitem>
528 <para>Select <emphasis
529 role="bold">Configuration</emphasis>.</para>
530 </listitem>
531
532 <listitem>
533 <para>The configurable parameters are:</para>
534
535 <itemizedlist>
536 <listitem>
537 <para><literal>deviceImageDir</literal>. This is the disk
538 location of the device image repository.</para>
539
540 <note>
541 <para>If no absolute path name is given it is assumed to
542 be relative to the installation directory.</para>
543 </note>
544 </listitem>
545
546 <listitem>
547 <para><literal>maxThreads</literal>. This number dictates
548 how many upgrades the system can manage at one time, either
549 individually launched or launched from the multi-device
550 screens. This value defaults to 20, which means that 20 uCPE
551 devices may be updated at one time.</para>
552 </listitem>
553
554 <listitem>
555 <para><literal>KeepAlive</literal>. This number represents
556 the number of seconds that a thread will be kept alive
557 before it is collected. If multiple installations are
558 occurring, this will keep the thread alive for X seconds
559 before it is released. If not released, it can be used by
560 the internal scheduling system as soon as it has completed
561 an upgrade.</para>
562 </listitem>
563 </itemizedlist>
564 </listitem>
565 </orderedlist></para>
566 </section>
567
568 <section id="related_functionality">
569 <title>Related Functionality for a uCPE device Upgrade</title>
570
571 <para>Each uCPE device can receive image files and use them to
572 upgrade. This can be done by selecting the uCPE device in the
573 <emphasis role="bold">System</emphasis> view and clicking the
574 <emphasis role="bold">Upgrade</emphasis> button. In the new window, an
575 upgrade image can be chosen from the <emphasis role="bold">Image
576 Files</emphasis> tab by selecting the image file from the list and
577 clicking the <emphasis role="bold">Install on Device</emphasis>
578 button.</para>
579
580 <para>Once an image is installed on the uCPE device, the image will be
581 available on the uCPE device and be visible in the <emphasis
582 role="bold">Releases</emphasis> tab. It can then be selected from the
583 list and the upgrade started by clicking the <emphasis
584 role="bold">Upgrade</emphasis> button.</para>
585 </section>
586 </section>
587 </section>
588</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)