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