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