summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml465
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/book.xml25
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/definitions_and_acronyms.xml146
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml720
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml2097
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/archive_list.pngbin0 -> 87667 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/collect_debug_logs.pngbin0 -> 47994 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/debug_settings.pngbin0 -> 32833 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/dev_file_mg.pngbin0 -> 138952 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/download_files.pngbin0 -> 79979 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/fault_events.pngbin0 -> 46986 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/prep_deploy.pngbin0 -> 125599 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/prep_execution.pngbin0 -> 127191 bytes
-rwxr-xr-xdoc/book-enea-nfv-access-getting-started/doc/images/vnf_space.pngbin19966 -> 44338 bytes
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml996
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/introduction.xml298
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/log_collector.xml392
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/net_config_options.xml740
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml169
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml537
-rw-r--r--doc/book-enea-nfv-access-getting-started/doc/vnf_mg.xml481
21 files changed, 3807 insertions, 3259 deletions
diff --git a/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml b/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml
index 9c60ebb..bd51b21 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/advanced_configurations.xml
@@ -4,152 +4,175 @@
4<chapter id="advanced_conf"> 4<chapter id="advanced_conf">
5 <title>Advanced Configurations</title> 5 <title>Advanced Configurations</title>
6 6
7 <para>This chapter describes possible configurations for select advanced 7 <para>This chapter describes possible configurations for advanced features
8 features such as the Hugepage Reservation Service, UEFI Secure Boot and Bare 8 such as the Hugepage Reservation Service, UEFI Secure Boot and Bare Metal
9 Metal Provisioning. These features are optional in the Enea NFV Access 9 Provisioning. These features are optional in the Enea NFV Access platform.
10 platform. If you do not intend to use these features, skip this 10 If you do not intend to use these features, skip this chapter.</para>
11 chapter.</para>
12 11
13 <section id="hugepage_reservation"> 12 <section id="bare_meta_prov">
14 <title>Hugepage Reservation Service</title> 13 <title>Bare Metal Provisioning</title>
15
16 <para>NFV Access implements an automatic hugepage allocation service that
17 is triggered at each startup. The service is skipped if hugepages have
18 been allocated in the kernel boot command line.</para>
19
20 <para>There are two strategies outlined for hugepage allocation:</para>
21 14
22 <itemizedlist> 15 <para>Bare Metal Provisioning can be used for automated deployment of the
23 <listitem> 16 Enea NFV Access Run Time Platform on a large number of uCPE devices. The
24 <para>If a system has an amount of memory up to 8GB, the allocation 17 uCPE devices may have no previous operating system installed, or are
25 algorithm will reserve up to 30% (no more than 2GB), for the OS and 18 reinstalled without preserving any existing data. Enea NFV Access Bare
26 the rest as 2MB hugepages.</para> 19 Metal Provisioning is based on standardized Pre-Boot Execution environment
27 </listitem> 20 (PXE) booting.</para>
28 21
29 <listitem> 22 <para>The Bare Metal Provisioning process begins by PXE booting an Enea
30 <para>If a system has an amount of memory that's higher than 8GB, the 23 NFV Access installer <literal>initramfs</literal> image. The installer
31 allocation algorithm will reserve all but 2GB of memory as 1GB 24 downloads a configuration file, as well as the Enea NFV Access Run Time
32 hugepages, leaving the rest (2GB) to be used by the OS.</para> 25 Platform image and then proceeds to install the system by dividing the
33 </listitem> 26 disk into 2 partitions: a GPT partition containing the GRUB boot loader
34 </itemizedlist> 27 and a second partition containing the Enea NFV Access Run Time Platform
28 root filesystem. When the installation is complete, the uCPE device is
29 automatically rebooted into Enea NFV Access Run Time Platform.</para>
35 30
36 <note> 31 <note>
37 <para>This is a best effort reservation after kernel boot, so the 32 <para>The <literal>.hddimg</literal>, <literal>initramfs</literal>, and
38 results may vary accordingly.</para> 33 <literal>bzImage</literal> files are available in the
34 <filename>Enea_NFV_Access_Run_Time_Platform_
35 &lt;processor&gt;_&lt;version&gt;-&lt;build_number&gt;.tar.gz</filename>
36 file you downloaded with your release.</para>
39 </note> 37 </note>
40 38
41 <section id="hugepage_customizing_auto"> 39 <section id="bare_meta_prov_prereq">
42 <title>Customizing Automatic Hugepage Reservation</title> 40 <title>Prerequisites</title>
43
44 <para>Configuration of Hugepage reservation is done in
45 <literal>/etc/enea-nfv-access/hugepages.cfg</literal>.</para>
46
47 <para><emphasis role="bold">Parameters used by the automatic algorithm:
48 </emphasis></para>
49 41
50 <itemizedlist spacing="compact"> 42 <itemizedlist>
51 <listitem> 43 <listitem>
52 <para><literal>hugepage_setup</literal>: Enables the automatic 44 <para>The uCPE devices to be installed are connected in a working
53 configuraiton algorithm. It has only one value, 45 PXE network boot environment. The PXE server can be set up using any
54 <literal>auto</literal>. For manual configuration comment or remove 46 Linux distribution that includes TFTP and DHCP software packages.
55 this parameter. Use the other parameter descriptions as a 47 Refer to the documentation for your distribution for setup
56 template/example.</para> 48 instructions.</para>
57 </listitem> 49 </listitem>
58 50
59 <listitem> 51 <listitem>
60 <para><literal>threshold_to_use_1g</literal>: Decides the threshold 52 <para>An HTTP server must be available and accessible from the uCPE
61 which instructs the algorithm to use 1GB hugepages. If a system's 53 devices in the provisioning network. Note that the installer will
62 memory is higher than <literal>threshold_to_use_1g</literal>, then 54 use the same interface that the uCPE device is PXE-booted from, to
63 the algorithm will use 1GB hugepages, otherwise it will use 2MB 55 obtain an IP address using DHCP and access the HTTP server.</para>
64 hugepages.</para>
65 </listitem> 56 </listitem>
66 57
67 <listitem> 58 <listitem>
68 <para><literal>percent_os_alloc</literal>: Decides how much memory 59 <para>The uCPE devices are preconfigured in BIOS to boot from the
69 to try to reserve for userspace applications. The algorithm will try 60 hard drive where the Enea NFV Access Run Time Platform will be
70 to reserve at least the value of <literal>percent_os_alloc</literal> 61 installed.</para>
71 of the total system memory for userspace applications.</para>
72 </listitem> 62 </listitem>
73 63
74 <listitem> 64 <listitem>
75 <para><literal>maximum_os_alloc_mb</literal>: Maximum amount of 65 <para>A remote management tool is available that can be used to set
76 memory to allocate for userspace applications. If 66 the next boot option to PXE and reboot the uCPE devices in order to
77 <literal>percent_os_alloc</literal> of the total system memory 67 begin the installation.</para>
78 exceeds <literal>maximum_os_alloc_mb</literal> then the maximum
79 allocated memory for userspace applications is
80 <literal>maximum_os_alloc_mb</literal>.</para>
81 </listitem> 68 </listitem>
82 </itemizedlist> 69 </itemizedlist>
70 </section>
83 71
84 <para><emphasis role="bold">Example of automatic Hugepage 72 <section id="bare_meta_prov_server">
85 Configuration:</emphasis></para> 73 <title>Server Configuration</title>
86
87 <programlisting> hugepage_setup = auto
88 threshold_to_use_1g = 8192
89 percent_os_alloc = 30
90 maximum_os_alloc_mb = 2048</programlisting>
91 74
92 <para>The following possible allocations can result (based on total 75 <para>The following images provided with your Enea NFV Access release
93 system memory available):</para> 76 need to be made available on the PXE and HTTP servers:</para>
94 77
95 <itemizedlist> 78 <orderedlist>
96 <listitem> 79 <listitem>
97 <para>2GB of memory: approximately 30% will be allocated for the OS 80 <para>Copy the Enea NFV Access installer
98 and the rest will be allocated as 2MB hugepages.</para> 81 <literal>initramfs</literal> image and kernel
82 <literal>bzImage</literal> for your uCPE device architecture to the
83 TFTP directory on the PXE server (e.g
84 <literal>/var/lib/tftpboot</literal>).</para>
99 </listitem> 85 </listitem>
100 86
101 <listitem> 87 <listitem>
102 <para>4GB of memory: approximately 30% will be allocated for the OS 88 <para>Compress the Enea NFV Access Run Time Platform
103 and the rest will be allocated as 2MB hugepages.</para> 89 <literal>.hddimg</literal> image for the uCPE device architecture
90 using <literal>gzip</literal> and copy the resulting
91 <literal>hddimg.gz</literal> file to the HTTP server.</para>
104 </listitem> 92 </listitem>
93 </orderedlist>
105 94
106 <listitem> 95 <section id="bare_meta_prov_install_config">
107 <para>16GB of memory: approximately 2GB will be allocated for the OS 96 <title>Installation Configuration File</title>
108 and the rest as 1GB hugepages.</para>
109 </listitem>
110 </itemizedlist>
111 97
112 <note> 98 <para>An installation configuration file needs to be prepared on the
113 <para>The memory allocated for the kernel and hugepages might vary 99 HTTP server. The format of the configuration file is a list of
114 slightly depending on how much memory is available.</para> 100 "<literal>name = value</literal>" pairs and the available parameters
115 </note> 101 are described below.</para>
116 </section>
117 102
118 <section id="hugepage_customizing_man"> 103 <para>Mandatory parameter(s):</para>
119 <title>Customizing Manual Hugepage Reservation</title>
120 104
121 <para>The automatic algorithm can be disabled and hugepages in turn, 105 <itemizedlist>
122 configured manually. To do this, comment the line which defines 106 <listitem>
123 <literal>hugepage_setup</literal> as <literal>auto</literal> and 107 <para><literal>image_url</literal>. The HTTP server URL used for
124 configure memory for each CPU socket in the following manner:</para> 108 downloading the Enea NFV Access Run Time Platform image.</para>
109 </listitem>
110 </itemizedlist>
125 111
126 <programlisting>&lt;NUMA node&gt;.&lt;hugepage size&gt; = &lt;number of pages&gt;</programlisting> 112 <para>Optional parameters:</para>
127 113
128 <para>Where <literal>&lt;NUMA node&gt;</literal> refers to a node which 114 <itemizedlist>
129 is part of the system's NUMA topology, <literal>&lt;hugepage 115 <listitem>
130 size&gt;</literal> decides what type of hugepages should be set and 116 <para><literal>install_drive</literal>. The name of the drive
131 <literal>&lt;number of hugepages&gt;</literal> is how many hugepages of 117 where the Enea NFV Access Run Time Platform will be installed (e.g
132 <literal>&lt;hugepage size&gt;</literal> should be allocated.</para> 118 <literal>/dev/sda</literal>). If not set, the installer will use
119 the largest detected (non-USB) drive on the uCPE device.</para>
120 </listitem>
133 121
134 <para>To list the available system nodes, run:</para> 122 <listitem>
123 <para><literal>prompt_user</literal>. If the parameter is set to
124 "yes", the installer will ask for confirmation before formatting
125 and partitioning the drive. The default behaviour is to proceed
126 automatically without any user interaction.</para>
127 </listitem>
128 </itemizedlist>
135 129
136 <programlisting>ls -d /sys/devices/system/node/node* </programlisting> 130 <para>Installation Configuration File Example:</para>
137 131
138 <para>To list available hugepage sizes, per node, run:</para> 132 <programlisting>image_url = http://192.168.1.100/enea-nfv-access-xeon-d.hddimg.gz
133install_drive = /dev/sda</programlisting>
139 134
140 <programlisting>ls -d /sys/devices/system/node/node*/hugepages/hugepages-*</programlisting> 135 <note>
136 <para>The installation configuration file needs to use the Linux
137 end-of-line format (\n), not the Windows format (\r\n).</para>
138 </note>
139 </section>
141 140
142 <para>Example of Manual Hugepage Configuration, configuring the system 141 <section id="bare_meta_prov_pxe">
143 to allocate three 1GB hugepages and 512 of 2MB hugepages on node:</para> 142 <title>PXE Configuration</title>
144 143
145 <programlisting>node0.2048kB = 512 144 <para>A PXE entry for the Enea NFV Access installation needs to be
146node0.1048576kB = 3 </programlisting> 145 added as the default boot selection in the pxelinux configuration file
146 (e.g <literal>/var/lib/tftpboot/pxelinux.cfg/default</literal>). The
147 PXE entry should have the following settings:</para>
147 148
148 <note> 149 <programlisting>default nfv_access
149 <para>Make sure there are no hugepages reserved in the kernel boot 150label nfv_access
150 command line, these will override any manual configuration done in the 151menu label ^NFV_ACCESS_INSTALLER
151 service.</para> 152kernel &lt;Path to kernel&gt;
152 </note> 153append root=/dev/ram0 initrd=&lt;Path to initramfs&gt; LABEL=pxe-installer \
154 INSTALL_CFG=http://&lt;Server IP&gt;/&lt;Path to install config file&gt; \
155 console=ttyS0,115200 earlyprintk=ttyS0,115200
156ipappend 2</programlisting>
157 </section>
158 </section>
159
160 <section id="bare_meta_prov_inst">
161 <title>Starting the Installation</title>
162
163 <para>To initiate the installation, set the boot device (for next boot
164 only) to PXE and reboot the uCPE devices. How to do this depends on the
165 remote management capabilities of the uCPE devices and may require
166 vendor-specific tools.</para>
167
168 <para>Example initiation using <literal>ipmitool</literal>:</para>
169
170 <programlisting>ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; chassis bootdev pxe
171ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; power reset </programlisting>
172
173 <para>The uCPE devices should be configured in BIOS to boot from the
174 installation drive first in order to automatically start the Enea NFV
175 Access Run Time Platform when the installation is finished.</para>
153 </section> 176 </section>
154 </section> 177 </section>
155 178
@@ -223,6 +246,11 @@ node0.1048576kB = 3 </programlisting>
223 <para>These certificates need to be manually enrolled in BIOS. The 246 <para>These certificates need to be manually enrolled in BIOS. The
224 exact details on how to proceed may vary depending the version of the 247 exact details on how to proceed may vary depending the version of the
225 UEFI firmware.</para> 248 UEFI firmware.</para>
249
250 <para>The UEFI firmware is normally shipped with factory preloaded
251 certificates. If these do not already include Certificates from Enea,
252 they will need to be appended or replaced with the Enea
253 Certificates.</para>
226 </section> 254 </section>
227 255
228 <section id="enable_secure_boot"> 256 <section id="enable_secure_boot">
@@ -234,173 +262,146 @@ node0.1048576kB = 3 </programlisting>
234 </section> 262 </section>
235 </section> 263 </section>
236 264
237 <section id="bare_meta_prov"> 265 <section id="hugepage_reservation">
238 <title>Bare Metal Provisioning</title> 266 <title>Hugepage Reservation Service</title>
239 267
240 <para>Bare Metal Provisioning can be used for automated deployment of the 268 <para>NFV Access implements an automatic hugepage allocation service that
241 Enea NFV Access Run Time Platform on a large number of uCPE devices. The 269 is triggered at each startup. The service is skipped if hugepages have
242 uCPE devices may have no previous operating system installed, or are 270 been allocated in the kernel boot command line.</para>
243 reinstalled without preserving any existing data. Enea NFV Access Bare
244 Metal Provisioning is based on standardized Pre-Boot Execution environment
245 (PXE) booting.</para>
246 271
247 <para>The Bare Metal Provisioning process begins by PXE booting an Enea 272 <para>There are two strategies outlined for hugepage allocation:</para>
248 NFV Access installer <literal>initramfs</literal> image. The installer 273
249 downloads a configuration file, as well as the Enea NFV Access Run Time 274 <itemizedlist>
250 Platform image and then proceeds to install the system by dividing the 275 <listitem>
251 disk into 2 partitions. A GPT partition containing the GRUB boot loader 276 <para>If a system has an amount of memory up to 8GB, the allocation
252 and a second partition containing the Enea NFV Access Run Time Platform 277 algorithm will reserve up to 30% (no more than 2GB), for the OS and
253 root filesystem. When the installation is complete, the uCPE device is 278 the rest as 2MB hugepages.</para>
254 automatically rebooted into Enea NFV Access Run Time Platform.</para> 279 </listitem>
280
281 <listitem>
282 <para>If a system has an amount of memory that's higher than 8GB, the
283 allocation algorithm will reserve all but 2GB of memory as 1GB
284 hugepages, leaving the rest (2GB) to be used by the OS.</para>
285 </listitem>
286 </itemizedlist>
255 287
256 <note> 288 <note>
257 <para>The <literal>.hddimg</literal>, <literal>initramfs</literal>, and 289 <para>This is a best effort reservation after kernel boot, so the
258 <literal>bzImage</literal> files are available in the 290 results may vary accordingly.</para>
259 Enea_NFV_Access_Run_Time_Platform_
260 &lt;processor&gt;_&lt;version&gt;-&lt;build_number&gt;.tar.gz file you
261 downloaded with your release.</para>
262 </note> 291 </note>
263 292
264 <section id="bare_meta_prov_prereq"> 293 <section id="hugepage_customizing_auto">
265 <title>Prerequisites</title> 294 <title>Customizing Automatic Hugepage Reservation</title>
266 295
267 <itemizedlist> 296 <para>Configuration of Hugepage reservation is done in
297 <literal>/etc/enea-nfv-access/hugepages.cfg</literal>.</para>
298
299 <para><emphasis role="bold">Parameters used by the automatic algorithm:
300 </emphasis></para>
301
302 <itemizedlist spacing="compact">
268 <listitem> 303 <listitem>
269 <para>The uCPE devices to be installed are connected in a working 304 <para><literal>hugepage_setup</literal>: Enables the automatic
270 PXE network boot environment. The PXE server can be set up using any 305 configuraiton algorithm. It has only one value,
271 Linux distribution that includes TFTP and DHCP software packages. 306 <literal>auto</literal>. For manual configuration comment or remove
272 Refer to the documentation for your distribution for setup 307 this parameter. Use the other parameter descriptions as a
273 instructions.</para> 308 template/example.</para>
274 </listitem> 309 </listitem>
275 310
276 <listitem> 311 <listitem>
277 <para>An HTTP server must be available and accessible from the uCPE 312 <para><literal>threshold_to_use_1g</literal>: Decides the threshold
278 devices in the provisioning network. Note that the installer will 313 which instructs the algorithm to use 1GB hugepages. If a system's
279 use the same interface that the uCPE device is PXE-booted from, to 314 memory is higher than <literal>threshold_to_use_1g</literal>, then
280 obtain an IP address using DHCP and access the HTTP server.</para> 315 the algorithm will use 1GB hugepages, otherwise it will use 2MB
316 hugepages.</para>
281 </listitem> 317 </listitem>
282 318
283 <listitem> 319 <listitem>
284 <para>The uCPE devices are preconfigured in BIOS to boot from the 320 <para><literal>percent_os_alloc</literal>: Decides how much memory
285 hard drive where the Enea NFV Access Run Time Platform will be 321 to try to reserve for userspace applications. The algorithm will try
286 installed.</para> 322 to reserve at least the value of <literal>percent_os_alloc</literal>
323 of the total system memory for userspace applications.</para>
287 </listitem> 324 </listitem>
288 325
289 <listitem> 326 <listitem>
290 <para>A remote management tool is available that can be used to set 327 <para><literal>maximum_os_alloc_mb</literal>: Maximum amount of
291 the next boot option to PXE and reboot the uCPE devices in order to 328 memory to allocate for userspace applications. If
292 begin the installation.</para> 329 <literal>percent_os_alloc</literal> of the total system memory
330 exceeds <literal>maximum_os_alloc_mb</literal> then the maximum
331 allocated memory for userspace applications is
332 <literal>maximum_os_alloc_mb</literal>.</para>
293 </listitem> 333 </listitem>
294 </itemizedlist> 334 </itemizedlist>
295 </section>
296 335
297 <section id="bare_meta_prov_server"> 336 <para><emphasis role="bold">Example of automatic Hugepage
298 <title>Server Configuration</title> 337 Configuration:</emphasis></para>
299 338
300 <para>The following images provided with your Enea NFV Access release 339 <programlisting>hugepage_setup = auto
301 need to be made available on the PXE and HTTP servers:</para> 340threshold_to_use_1g = 8192
341percent_os_alloc = 30
342maximum_os_alloc_mb = 2048</programlisting>
302 343
303 <orderedlist> 344 <para>The following possible allocations can result (based on total
345 system memory available):</para>
346
347 <itemizedlist>
304 <listitem> 348 <listitem>
305 <para>Copy the Enea NFV Access installer 349 <para>2GB of memory: approximately 30% will be allocated for the OS
306 <literal>initramfs</literal> image and kernel 350 and the rest will be allocated as 2MB hugepages.</para>
307 <literal>bzImage</literal> for your uCPE device architecture to the
308 TFTP directory on the PXE server (e.g
309 <literal>/var/lib/tftpboot</literal>).</para>
310 </listitem> 351 </listitem>
311 352
312 <listitem> 353 <listitem>
313 <para>Compress the Enea NFV Access Run Time Platform 354 <para>4GB of memory: approximately 30% will be allocated for the OS
314 <literal>.hddimg</literal> image for the uCPE device architecture 355 and the rest will be allocated as 2MB hugepages.</para>
315 using <literal>gzip</literal> and copy the resulting
316 <literal>hddimg.gz</literal> file to the HTTP server.</para>
317 </listitem> 356 </listitem>
318 </orderedlist>
319
320 <section id="bare_meta_prov_install_config">
321 <title>Installation Configuration File</title>
322
323 <para>An installation configuration file needs to be prepared on the
324 HTTP server. The format of the configuration file is a list of
325 "<literal>name = value</literal>" pairs and the available parameters
326 are described below.</para>
327 357
328 <para>Mandatory parameters:</para> 358 <listitem>
329 359 <para>16GB of memory: approximately 2GB will be allocated for the OS
330 <itemizedlist> 360 and the rest as 1GB hugepages.</para>
331 <listitem> 361 </listitem>
332 <para><literal>image_url</literal>. The HTTP server URL used for 362 </itemizedlist>
333 downloading the Enea NFV Access Run Time Platform image. This
334 image will be installed on the uCPE device(s) in the
335 <literal>hddimg.gz</literal> format.</para>
336 </listitem>
337 </itemizedlist>
338
339 <para>Optional parameters:</para>
340
341 <itemizedlist>
342 <listitem>
343 <para><literal>install_drive</literal>. The name of the drive
344 where the Enea NFV Access Run Time Platform will be installed (e.g
345 <literal>/dev/sda</literal>). If not set, the installer will use
346 the largest detected (non-USB) drive on the uCPE device.</para>
347 </listitem>
348 363
349 <listitem> 364 <note>
350 <para><literal>prompt_user</literal>. If the parameter is set to 365 <para>The memory allocated for the kernel and hugepages might vary
351 "yes", the installer will ask for confirmation before formatting 366 slightly depending on how much memory is available.</para>
352 and partitioning the drive. The default behaviour is to proceed 367 </note>
353 automatically without any user interaction.</para> 368 </section>
354 </listitem>
355 </itemizedlist>
356 369
357 <para>Installation Configuration File Example:</para> 370 <section id="hugepage_customizing_man">
371 <title>Customizing Manual Hugepage Reservation</title>
358 372
359 <programlisting>image_url = http://192.168.1.100/enea-nfv-access-xeon-d.hddimg.gz 373 <para>The automatic algorithm can be disabled and hugepages in turn,
360install_drive = /dev/sda</programlisting> 374 configured manually. To do this, comment the line which defines
375 <literal>hugepage_setup</literal> as <literal>auto</literal> and
376 configure memory for each CPU socket in the following manner:</para>
361 377
362 <note> 378 <programlisting>&lt;NUMA node&gt;.&lt;hugepage size&gt; = &lt;number of pages&gt;</programlisting>
363 <para>The installation configuration file needs to use the Linux
364 end-of-line format (\n), not the Windows format (\r\n).</para>
365 </note>
366 </section>
367 379
368 <section id="bare_meta_prov_pxe"> 380 <para>Where <literal>&lt;NUMA node&gt;</literal> refers to a node which
369 <title>PXE Configuration</title> 381 is part of the system's NUMA topology, <literal>&lt;hugepage
382 size&gt;</literal> decides what type of hugepages should be set and
383 <literal>&lt;number of hugepages&gt;</literal> is how many hugepages of
384 <literal>&lt;hugepage size&gt;</literal> should be allocated.</para>
370 385
371 <para>A PXE entry for the Enea NFV Access installation needs to be 386 <para>To list the available system nodes, run:</para>
372 added as the default boot selection in the pxelinux configuration file
373 (e.g <literal>/var/lib/tftpboot/pxelinux.cfg/default</literal>). The
374 PXE entry should have the following settings:</para>
375 387
376 <programlisting>default nfv_access 388 <programlisting>ls -d /sys/devices/system/node/node* </programlisting>
377label nfv_access
378menu label ^NFV_ACCESS_INSTALLER
379kernel &lt;Path to kernel&gt;
380append root=/dev/ram0 initrd=&lt;Path to initramfs&gt; LABEL=pxe-installer \
381 INSTALL_CFG=http://&lt;Server IP&gt;/&lt;Path to install config file&gt; \
382 console=ttyS0,115200 earlyprintk=ttyS0,115200
383ipappend 2
384 </programlisting>
385 </section>
386 </section>
387 389
388 <section id="bare_meta_prov_inst"> 390 <para>To list available hugepage sizes, per node, run:</para>
389 <title>Starting the Installation</title>
390 391
391 <para>To initiate the installation, set the boot device (for next boot 392 <programlisting>ls -d /sys/devices/system/node/node*/hugepages/hugepages-*</programlisting>
392 only) to PXE and reboot the uCPE devices. How to do this depends on the
393 remote management capabilities of the uCPE devices and may require
394 vendor-specific tools.</para>
395 393
396 <para>Example initiation using <literal>ipmitool</literal>:</para> 394 <para>Example of Manual Hugepage Configuration, configuring the system
395 to allocate three 1GB hugepages and 512 of 2MB hugepages on node:</para>
397 396
398 <programlisting>ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; chassis bootdev pxe 397 <programlisting>node0.2048kB = 512
399ipmitool -U &lt;user&gt; -P &lt;password&gt; -H &lt;uCPE device IPMI IP address&gt; power reset </programlisting> 398node0.1048576kB = 3 </programlisting>
400 399
401 <para>The uCPE devices should be configured in BIOS to boot from the 400 <note>
402 installation drive first in order to automatically start the Enea NFV 401 <para>Make sure there are no hugepages reserved in the kernel boot
403 Access Run Time Platform when the installation is finished.</para> 402 command line, these will override any manual configuration done in the
403 service.</para>
404 </note>
404 </section> 405 </section>
405 </section> 406 </section>
406</chapter> \ No newline at end of file 407</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/book.xml b/doc/book-enea-nfv-access-getting-started/doc/book.xml
index 893546b..d148f3b 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/book.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/book.xml
@@ -16,17 +16,26 @@
16 xmlns:xi="http://www.w3.org/2001/XInclude" /> 16 xmlns:xi="http://www.w3.org/2001/XInclude" />
17 17
18 <xi:include href="introduction.xml" 18 <xi:include href="introduction.xml"
19 xmlns:xi="http://www.w3.org/2001/XInclude" />
20
21 <xi:include href="definitions_and_acronyms.xml"
22 xmlns:xi="http://www.w3.org/2001/XInclude" /> 19 xmlns:xi="http://www.w3.org/2001/XInclude" />
23 20
24 <xi:include href="getting_started_nfv_access.xml" 21 <xi:include href="installation_guide.xml"
25 xmlns:xi="http://www.w3.org/2001/XInclude" /> 22 xmlns:xi="http://www.w3.org/2001/XInclude" />
26 23
27 <xi:include href="getting_started_ucpe_manager.xml" 24 <xi:include href="upgrade_ena.xml"
28 xmlns:xi="http://www.w3.org/2001/XInclude" /> 25 xmlns:xi="http://www.w3.org/2001/XInclude" />
29 26
30 <xi:include href="advanced_configurations.xml" 27 <xi:include href="advanced_configurations.xml"
31 xmlns:xi="http://www.w3.org/2001/XInclude" /> 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="troubleshooting.xml"
40 xmlns:xi="http://www.w3.org/2001/XInclude" />
32</book> 41</book>
diff --git a/doc/book-enea-nfv-access-getting-started/doc/definitions_and_acronyms.xml b/doc/book-enea-nfv-access-getting-started/doc/definitions_and_acronyms.xml
deleted file mode 100644
index e5f81fc..0000000
--- a/doc/book-enea-nfv-access-getting-started/doc/definitions_and_acronyms.xml
+++ /dev/null
@@ -1,146 +0,0 @@
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="def_and_acr">
5 <title>Definitions and Acronyms</title>
6
7 <section id="definitions">
8 <title>Definitions</title>
9
10 <table>
11 <title>Definitions</title>
12
13 <tgroup cols="2">
14 <colspec align="left" colname="1" colwidth="1*" />
15
16 <colspec align="left" colname="2" colwidth="3*" />
17
18 <tbody>
19 <row>
20 <entry>Enea NFV Access</entry>
21
22 <entry>The Enea NFV Access Run Time Platform and uCPE
23 Manager.</entry>
24 </row>
25
26 <row>
27 <entry>Enea NFV Access Run Time Platform</entry>
28
29 <entry>A lightweight, multi-architecture virtualization platform,
30 supporting Virtual Machines (KVM / QEMU).</entry>
31 </row>
32
33 <row>
34 <entry>Enea uCPE Manager</entry>
35
36 <entry>Enea Universal Customer Premises Equipment Manager.</entry>
37 </row>
38
39 <row>
40 <entry>uCPE device</entry>
41
42 <entry>A whitebox (e.g. Intel XeonD) running Enea NFV Access Run
43 Time platform.</entry>
44 </row>
45 </tbody>
46 </tgroup>
47 </table>
48 </section>
49
50 <section id="acronyms">
51 <title>Acronyms</title>
52
53 <table>
54 <title>acronyms</title>
55
56 <tgroup cols="2">
57 <colspec align="left" colname="1" colwidth="1*" />
58
59 <colspec align="left" colname="2" colwidth="3*" />
60
61 <tbody>
62 <row>
63 <entry>API</entry>
64
65 <entry>Application Programming Interface.</entry>
66 </row>
67
68 <row>
69 <entry>DPDK</entry>
70
71 <entry>Data Plane Development Kit.</entry>
72 </row>
73
74 <row>
75 <entry>EFI</entry>
76
77 <entry>Extensible Firmware Interface.</entry>
78 </row>
79
80 <row>
81 <entry>FCAPS</entry>
82
83 <entry>Fault-management, Configuration, Accounting, Performance
84 and Security.</entry>
85 </row>
86
87 <row>
88 <entry>NETCONF</entry>
89
90 <entry>Network Configuration Protocol.</entry>
91 </row>
92
93 <row>
94 <entry>NFV</entry>
95
96 <entry>Network Functions Virtualization.</entry>
97 </row>
98
99 <row>
100 <entry>OVS</entry>
101
102 <entry>Open vSwitch.</entry>
103 </row>
104
105 <row>
106 <entry>UEFI</entry>
107
108 <entry>Unified Extensible Firmware Interface.</entry>
109 </row>
110
111 <row>
112 <entry>SR-IOV</entry>
113
114 <entry>Single Root Input/Output Virtualization.</entry>
115 </row>
116
117 <row>
118 <entry>PCI</entry>
119
120 <entry>Peripheral Component Interconnect.</entry>
121 </row>
122
123 <row>
124 <entry>PCI Passthrough</entry>
125
126 <entry>PCI Passthrough allows for use of a physical PCI device,
127 e.g. a network card inside a VM. If you "PCI passthrough" a
128 device, the device is not available to the host anymore.</entry>
129 </row>
130
131 <row>
132 <entry>REST</entry>
133
134 <entry>Representational State Transfer.</entry>
135 </row>
136
137 <row>
138 <entry>VNF</entry>
139
140 <entry>Virtual Network Function.</entry>
141 </row>
142 </tbody>
143 </tgroup>
144 </table>
145 </section>
146</chapter>
diff --git a/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml b/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml
deleted file mode 100644
index 7ddf113..0000000
--- a/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml
+++ /dev/null
@@ -1,720 +0,0 @@
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="plat-release-content">
5 <title>Getting Started with Enea NFV Access</title>
6
7 <section id="access_installer">
8 <title>Enea NFV Access Run Time Platform Installer</title>
9
10 <para>The current release supports two methods of installation:</para>
11
12 <itemizedlist>
13 <listitem>
14 <para>Manual installation from a USB stick using the Enea NFV Access
15 Web-installer, which guarantees a clean installation of NFV Access on
16 a uCPE device.</para>
17 </listitem>
18
19 <listitem>
20 <para>Mass installation and automated deployment using Bare Metal
21 Provisioning.</para>
22 </listitem>
23 </itemizedlist>
24
25 <para>For more information about Bare Metal Provisioning please refer to
26 section <olink targetdoc="book_enea_nfv_access_getting_started"
27 targetptr="bare_meta_prov">Bare Metal Provisioning in <xi:include
28 href="../../s_docbuild/olinkdb/pardoc-names.xml"
29 xmlns:xi="http://www.w3.org/2001/XInclude"
30 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
31 Manual.</para>
32
33 <section id="prereq">
34 <title>Prerequisites</title>
35
36 <para>To install the Enea NFV Access Run Time Platform, 3 things are
37 required: a USB stick (16GB or larger), a development machine with root
38 permissions (Linux or Windows) and a uCPE device.</para>
39
40 <para>Minimal requirements for the uCPE device:</para>
41
42 <itemizedlist spacing="compact">
43 <listitem>
44 <para>EFI and virtualization support.</para>
45 </listitem>
46
47 <listitem>
48 <para>2 cores</para>
49 </listitem>
50
51 <listitem>
52 <para>4GB RAM</para>
53 </listitem>
54
55 <listitem>
56 <para>Storage Device (SSD recommended).</para>
57 </listitem>
58 </itemizedlist>
59
60 <para>BIOS settings that need to be enabled:</para>
61
62 <itemizedlist spacing="compact">
63 <listitem>
64 <para>EFI</para>
65 </listitem>
66
67 <listitem>
68 <para>Intel Virtualization Technology (VT-x)</para>
69 </listitem>
70
71 <listitem>
72 <para>Intel Virtualization Technology for Directed I/O (VT-d)</para>
73 </listitem>
74
75 <listitem>
76 <para>SR-IOV</para>
77 </listitem>
78 </itemizedlist>
79 </section>
80
81 <section condition="hidden" id="man_installer">
82 <title>Installer Setup and Usage for a manual installation</title>
83
84 <para><emphasis role="bold">To install Enea NFV Access Run Time Platform
85 on a physical drive</emphasis></para>
86
87 <orderedlist>
88 <listitem>
89 <para>Go to the installer location: <programlisting># cd &lt;path_to_EneaNFV_Access_folder&gt;/&lt;architecture&gt;/
90install/nfv-installer/script-installer</programlisting></para>
91 </listitem>
92
93 <listitem>
94 <para>Execute the installer script: <programlisting># sudo ./nfv_installer.sh</programlisting></para>
95 </listitem>
96
97 <listitem>
98 <para>Optionally, press ENTER to see the list of available
99 commands:<programlisting>help - displays a guide on how to use the installer
100list-params - lists all available parameters
101list-steps - lists the installer steps and the parameters that they depend on
102set - sets a parameter (e.g. <literal>set drive=/dev/sda</literal>)
103clear - clears a parameter (e.g. <literal>clear drive</literal>)
104list-partitions - lists current drives and partitions
105dry - performs a simulation test run
106run - executes the installer, using the values you set for each parameter
107q or quit - exits the script</programlisting></para>
108 </listitem>
109
110 <listitem>
111 <para>Set the required parameters depending on what steps you want
112 to run:</para>
113
114 <note>
115 <para>When using the installer for the first time, make sure to
116 set ALL parameters in order to be able to run all steps. See
117 Example 2 for details.</para>
118 </note>
119
120 <para><programlisting># set &lt;parameter_name&gt;=&lt;parameter_value&gt;</programlisting></para>
121
122 <itemizedlist spacing="compact">
123 <listitem>
124 <para><parameter>drive=&lt;/dev/sdaX&gt;</parameter> - sets the
125 drive which will be partitioned.</para>
126 </listitem>
127
128 <listitem>
129 <para><parameter>grub_binary=&lt;file&gt;</parameter> - points
130 to the <filename>GRUB</filename> executable, which will be
131 installed where <filename>grub_destination</filename> is
132 set.</para>
133 </listitem>
134
135 <listitem>
136 <para><parameter>grub_destination=&lt;drive&gt;</parameter> -
137 specifies the partition where <filename>GRUB</filename> will be
138 installed.</para>
139 </listitem>
140
141 <listitem>
142 <para><parameter>rootfs_destination=&lt;drive&gt;</parameter> -
143 specifies the partition where the <filename>rootfs</filename>
144 will be deployed, used by <filename>GRUB</filename> to boot
145 from.</para>
146 </listitem>
147
148 <listitem>
149 <para><parameter>rootfs_targz=&lt;rootfs.tar.gz
150 file&gt;</parameter> - sets the archive of the Enea NFV Access
151 <filename>rootfs</filename> you wish to unpack. The archive will
152 be unpacked where <filename>rootfs_destination</filename> is
153 set. Which type of archive file you unpack depends on whether
154 you are booting from an SSD/HDD or from a USB drive.</para>
155 </listitem>
156 </itemizedlist>
157 </listitem>
158
159 <listitem>
160 <para>Optionally, perform a test run before affecting the actual
161 layout of the physical media, with the command: <programlisting>dry</programlisting></para>
162 </listitem>
163
164 <listitem>
165 <para>Run the installer: <programlisting>run</programlisting></para>
166 </listitem>
167
168 <listitem>
169 <para>Exit the script: <programlisting>quit</programlisting></para>
170 </listitem>
171 </orderedlist>
172
173 <para>The Enea NFV Access installer creates a bootable media by
174 performing three steps. Each of the following 3 steps is executed or not
175 depending on whether certain parameters are set:</para>
176
177 <itemizedlist>
178 <listitem>
179 <para>Format drive. Creates a 512MB partition to be used by
180 <filename>GRUB</filename>, and another for use by the
181 <filename>rootfs</filename>. The second partition should occupy the
182 rest of the physical media, minus the first partition. This step
183 depends on setting these parameter(s): <programlisting>drive=</programlisting></para>
184 </listitem>
185
186 <listitem>
187 <para>GRUB install. Installs the <literal>grub_binary</literal> on
188 the drive set for <literal>grub_destination</literal>. A
189 <filename>grub.cfg</filename> file is created. This file is
190 configured by the user, to boot from the
191 <literal>rootfs_destination</literal>. This step depends on setting
192 these parameter(s):<programlisting>grub_destination=
193grub_binary=
194rootfs_destination=</programlisting></para>
195 </listitem>
196
197 <listitem>
198 <para>Root Filesystem install. Copies and unpacks the files found in
199 <literal>rootfs_targz</literal> to the
200 <literal>rootfs_destination</literal>. This step depends on setting
201 these parameter(s):<programlisting>rootfs_targz=
202rootfs_destination=</programlisting></para>
203 </listitem>
204 </itemizedlist>
205
206 <para>After using the installer and setting up the bootable media,
207 connect it to the uCPE device and configure the uCPE device to use it as
208 a primary boot device.</para>
209 </section>
210
211 <section id="auto_installer">
212 <title>Creating a bootable USB stick</title>
213
214 <para>In order to install the Enea NFV Access Run Time Platform, you
215 must first create a bootable USB stick with the image you intend to
216 install. Follow the example below to proceed.</para>
217
218 <note>
219 <para>The <literal>.hddimg</literal> image is available in the
220 Enea_NFV_Access_Run_Time_Platform_
221 &lt;processor&gt;_&lt;version&gt;-build&lt;build_number&gt;.tar.gz
222 file you downloaded with your release.</para>
223 </note>
224
225 <para><emphasis role="bold">Create a bootable USB stick
226 image</emphasis></para>
227
228 <orderedlist>
229 <listitem>
230 <para>Copy the <literal>.hddimg</literal> image file provided by
231 Enea, onto a development machine.</para>
232 </listitem>
233
234 <listitem>
235 <para>Connect the USB stick to the development machine and identify
236 the device name given by the system with <command>lsblk</command>:
237 <programlisting>NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
238sda 8:0 1 28.7G 0 disk
239sdb 8:0 0 111.8G 0 disk
240|-sdb1 8:1 0 111.8G 0 part</programlisting></para>
241 </listitem>
242
243 <listitem>
244 <para>Copy the <literal>.hddimg</literal> image onto the USB stick,
245 e.g: <programlisting>sudo dd if=./enea-nfv-access-&lt;machine&gt;.hddimg \
246of=/dev/sdb bs=4M conv=fsync</programlisting></para>
247 </listitem>
248 </orderedlist>
249
250 <para>Where <filename>enea-nfv-access-&lt;machine&gt;.hddimg
251 </filename>is the <literal>.hddimg</literal> file and
252 <literal>sdb</literal> is the assigned USB device name.</para>
253 </section>
254
255 <section id="install_ena_stick">
256 <title>Installing Enea NFV Access</title>
257
258 <para><emphasis role="bold">How to install the Enea NFV Access Run Time
259 Platform using a bootable USB stick image</emphasis></para>
260
261 <orderedlist>
262 <listitem>
263 <para>Plug the USB stick into the uCPE device. Connect a laptop
264 directly into one of the ports that will not later be chosen as a
265 WAN port. No other ports should be connected.</para>
266 </listitem>
267
268 <listitem>
269 <para>Power up the uCPE device and boot the USB stick. Verify that
270 the USB stick is selected from the BIOS boot menu.</para>
271 </listitem>
272
273 <listitem>
274 <para>Once the USB stick is properly booted, the Web-installer
275 application starts automatically and can be accessed in a web
276 browser at <literal>http://172.16.1.1</literal> (port 80).</para>
277
278 <para>On the first page of the Web-installer, the user should fill
279 in:</para>
280
281 <itemizedlist>
282 <listitem>
283 <para><emphasis role="bold">The uCPE Manager IP
284 Address</emphasis>.</para>
285 </listitem>
286
287 <listitem>
288 <para><emphasis role="bold">The Device ID</emphasis>. The unique
289 identifier of the uCPE device.</para>
290 </listitem>
291
292 <listitem>
293 <para><emphasis role="bold">Customer Tags</emphasis>. They are
294 used for <link linkend="zero_touch_prov">Zero Touch Provisining
295 (ZTP)</link> and can be left empty. What can be entered here (as
296 needed), are the tag(s) specified when creating an offline
297 configuration in the uCPE Manager.</para>
298 </listitem>
299 </itemizedlist>
300
301 <para>On the second page of the Web-installer, the user should fill
302 in:</para>
303
304 <itemizedlist>
305 <listitem>
306 <para><emphasis role="bold">The Layer 3 configuration of WAN
307 Interface(s)</emphasis>. Static or Dynamic IP must be
308 specified.</para>
309
310 <para>During network configuration, WAN cables will be plugged
311 into the device in order to identify ports and make them
312 available for configuration. Each port with a physically
313 connected cable will be automatically set as a WAN port and must
314 be configured (DHCP is the default setting). The user needs to
315 connect the same quantity of cables as the number of WAN ports
316 that he wishes to configure. No LAN ports should be connected
317 nor configured at this time. The configured WAN cables cannot be
318 removed after being configured.</para>
319
320 <note>
321 <para>The LAN port used to access the Web-installer from the
322 laptop will not be shown and cannot be configured.</para>
323 </note>
324 </listitem>
325
326 <listitem>
327 <para><emphasis role="bold">The Management Interface</emphasis>.
328 The interface that will be used by the uCPE Manager to
329 communicate with the device.</para>
330 </listitem>
331 </itemizedlist>
332 </listitem>
333
334 <listitem>
335 <para>When the user has completed the configuration steps in the
336 Web-installer, NFV Access is installed on the hard drive. The
337 largest drive found on the device will be used for
338 installation.</para>
339 </listitem>
340 </orderedlist>
341 </section>
342
343 <section id="boot_ena">
344 <title>Booting NFV Access</title>
345
346 <para>When the installation has finished successfully, the user should
347 remove the USB stick before confirming the reboot of the device in
348 Web-installer and ensure that BIOS is configured to boot from the hard
349 drive.</para>
350
351 <para>When configured with the Web-installer GUI, the uCPE device
352 start-up sequence will configure the interfaces accordingly and try to
353 register the device in the uCPE manager. If connectivity is established
354 with the uCPE manager server and a device with a matching Device ID is
355 found, the configuration is successful, and the connection is
356 established.</para>
357
358 <note>
359 <para>If NFV Access was installed by Bare Metal Provisioning, the
360 Web-installer will launch at start-up expecting the user to provide
361 the post-installation configuration. The Web-installer will be
362 launched on port 80 for post-installation configuration: <literal>
363 http://172.16.1.1</literal>.</para>
364 </note>
365
366 <para>In case of failure, the user should remove all WAN cables,
367 re-attach the laptop, reboot the device and then access the
368 Web-installer on <literal>http://172.16.1.1</literal>.</para>
369
370 <note>
371 <para>To make a new connection attempt with the uCPE manager server
372 using the existing configuration, just reboot the uCPE device. This
373 can for example be useful if the uCPE device was added in the uCPE
374 manager after it was already started.</para>
375 </note>
376 <note>
377 <para>After having established a successful connection with the uCPE
378 Manager, the user will connect any LAN cable(s) that should be
379 connected to the device.</para>
380 </note>
381 </section>
382
383 <section condition="hidden" id="examples">
384 <title>Examples</title>
385
386 <para>Below are a few examples of setups that the Enea NFV Access
387 installer can be used for:</para>
388
389 <itemizedlist>
390 <listitem xreflabel="example_one">
391 <para>Partitioning a drive:</para>
392
393 <programlisting>set drive=/dev/sda
394run</programlisting>
395 </listitem>
396
397 <listitem xreflabel="example_two">
398 <para>Partitioning a drive, installing GRUB, and a Root
399 Filesystem:</para>
400
401 <programlisting>set drive=/dev/sda
402set grub_destination=/dev/sda1
403set grub_binary=/home/user/grub-binary.efi
404set rootfs_destination=/dev/sda2
405set rootfs_targz=/home/user/rootfs.tar.gz
406run</programlisting>
407 </listitem>
408
409 <listitem xreflabel="example_three">
410 <para>Deploying ONLY a root filesystem:</para>
411
412 <programlisting>set rootfs_destination=/dev/sda2
413set rootfs_targz=/home/user/rootfs.tar.gz
414run</programlisting>
415 </listitem>
416 </itemizedlist>
417 </section>
418 </section>
419
420 <section condition="hidden" id="release-content">
421 <title>NFV Access Release content</title>
422
423 <para>The NFV Access 1.1 Release contains along with other items,
424 documentation, pre-built kernels and images, a bootloader and a
425 SDK.</para>
426
427 <para>The directories structure is detailed below:</para>
428
429 <programlisting>-- documentation/
430 /* NFV Access documentation */
431-- xeon-d/
432 /* artifacts for the host side */
433 -- deb/
434 /* deb packages */
435 -- images/
436 -- enea-image-virtualization-host
437 /* precompiled artifacts for the Host release image */
438 -- various artifacts
439 -- enea-image-virtualization-host-sdk
440 /* precompiled artifacts for the Host SDK image.
441 The SDK image contains userspace tools and kernel
442 configurations necessary for developing, debugging
443 and profiling applications and kernel modules */
444 -- various artifacts
445 -- sdk
446 /* NFV Access SDK for the host */
447 -- enea-glibc-x86_64-enea-image-virtualization-host-sdk /
448 -corei7-64-toolchain-7.0.sh
449 /* self-extracting archive installing
450 cross-compilation toolchain for the host */
451-- qemux86-64
452 /* artifacts for the guest side */
453 -- deb/
454 /* deb packages */
455 -- images/
456 -- enea-image-virtualization-guest
457 /* precompiled artifacts for the Guest image */
458 -- various artifacts
459 -- sdk
460 /* NFV Access SDK for the guest */
461 -- enea-glibc-x86_64-enea-image-virtualization-guest-sdk /
462 -core2-64-toolchain-7.0.sh
463 /* self-extracting archive installing cross-compilation
464 toolchain for the guest (QEMU x86-64) */</programlisting>
465
466 <para>For each combination of image and uCPE device, the following set of
467 artifacts is available:</para>
468
469 <programlisting>-- bzImage
470 /* kernel image */
471-- bzImage-&lt;target&gt;.bin
472 /* kernel image, same as above */
473-- config-&lt;target&gt;.config
474 /* kernel configuration file */
475-- core-image-minimal-initramfs-&lt;target&gt;.cpio.gz
476 /* cpio archive of the initramfs */
477-- core-image-minimal-initramfs-&lt;target&gt;.qemuboot.conf
478 /* qemu config file for the initramfs image */
479-- &lt;image-name&gt;-&lt;target&gt;.ext4
480 /* EXT4 image of the rootfs */
481-- &lt;image-name&gt;-&lt;target&gt;.hddimg
482 /* msdos filesystem containing syslinux, kernel, initrd and rootfs image */
483-- &lt;image-name&gt;-&lt;target&gt;.iso
484 /* CD .iso image */
485-- &lt;image-name&gt;-&lt;target&gt;.qemuboot.conf
486 /* qemu config file for the image */
487-- &lt;image-name&gt;-&lt;target&gt;.tar.gz
488 /* tar archive of the image */
489-- &lt;image-name&gt;-&lt;target&gt;.wic
490 /* Wic image */
491-- microcode.cpio
492 /* kernel microcode data */
493-- modules-&lt;target&gt;.tgz
494 /* external kernel modules */
495-- ovmf.*.qcow2
496 /* ovmf firmware for uefi support in qemu */
497-- rmc.db
498 /* Central RMC Database */
499-- systemd-bootx64.efi
500 /* systemd-boot EFI file */
501-- grub-efi-bootx64.efi
502 /* GRUB EFI file */</programlisting>
503 </section>
504
505 <section condition="hidden" id="prebuilt-artifacts">
506 <title>How to use the Prebuilt Artifacts</title>
507
508 <section id="boot-ramdisk">
509 <title>Booting Enea NFV Access using RAMDISK</title>
510
511 <para>There may be use cases, especially at first target ramp-up, where
512 the HDD/SDD has no partitions and you need to prepare the disks for
513 boot. Booting from ramdisk can help with this task.</para>
514
515 <para>The prerequisites needed to proceed:</para>
516
517 <itemizedlist>
518 <listitem>
519 <para>Enea NFV Access ext4 rootfs image -
520 enea-nfv-access-xeon-d.ext4.gz</para>
521 </listitem>
522
523 <listitem>
524 <para>Enea NFV Access kernel image - bzImage</para>
525 </listitem>
526
527 <listitem>
528 <para>BIOS has PXE boot enabled</para>
529 </listitem>
530
531 <listitem>
532 <para>PXE/tftp server configured and connected (ethernet) to
533 target.</para>
534 </listitem>
535 </itemizedlist>
536
537 <para>Unzip enea-nfv-access-xeon-d.ext4 and copy bzImage and
538 enea-nfv-access-xeon-d.ext4 images to the tftpserver configured for PXE
539 boot.</para>
540
541 <para>Use the following as an example for the PXE configuration
542 file:</para>
543
544 <programlisting>default vesamenu.c32
545prompt 1
546timeout 0
547
548label el_ramfs
549 menu label ^EneaLinux_RAMfs
550 kernel bzImage
551 append root=/dev/ram0 initrd=enea-nfv-access-xeon-d.ext4 /
552 ramdisk_size=1200000 console=ttyS0,115200 eralyprintk=ttyS0,115200</programlisting>
553
554 <para>Restart the target. Then enter (F11) in the Boot Menu and select
555 the Ethernet interface used for PXE boot. From the PXE Boot Menu select
556 <emphasis role="bold">Enea NFV Access_RAMfs</emphasis>. Once the Enea
557 NFV Access is started you can partition the HDD/SDD and install GRUB as
558 described in in the following section.</para>
559 </section>
560
561 <section id="install-grub">
562 <title>Partitioning a new harddisk and installing GRUB</title>
563
564 <para>The prerequisites needed:</para>
565
566 <itemizedlist>
567 <listitem>
568 <para>grub (<literal>grub-efi-bootx64.efi</literal>) - availalble as
569 a pre-built artifact under
570 <literal>xeon-d/images/enea-nfv-access</literal>.</para>
571 </listitem>
572
573 <listitem>
574 <para><literal>e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb,/</literal></para>
575
576 <para><literal>dosfstools_4.1-r0.0_amd64.deb</literal> - available
577 under <literal>xeon-d/deb</literal>.</para>
578 </listitem>
579 </itemizedlist>
580
581 <para>Proceed using the following steps:</para>
582
583 <orderedlist>
584 <listitem>
585 <para>Boot target with Enea NFV Access from RAMDISK</para>
586 </listitem>
587
588 <listitem>
589 <para>Install prerequisite packages:</para>
590
591 <programlisting>&gt; dpkg -i e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb
592&gt; dpkg -i dosfstools_4.1-r0.0_amd64.deb</programlisting>
593 </listitem>
594
595 <listitem>
596 <para>Partition the disk:</para>
597
598 <programlisting>&gt; fdisk /dev/sda
599fdisk&gt; g {GPT partition type}
600fdisk&gt; n
601fdisk&gt; 1
602fdisk&gt; {default start part}
603fdisk&gt; +512M
604fdisk&gt; t
605fdisk&gt; 1 {ESP/EFI partition}
606fdisk&gt; n
607fdisk&gt; 2
608fdisk&gt; {default start part}
609fdisk&gt; +18G
610fdisk&gt; 3
611fdisk&gt; {default start part}
612fdisk&gt; +20G
613...
614fdisk&gt; 7
615fdisk&gt; {default start part}
616fdisk&gt; {default end end part}
617
618fdisk&gt; p {print partion table}
619fdisk&gt; w {write to disk}
620fdisk&gt; q</programlisting>
621 </listitem>
622
623 <listitem>
624 <para>Format the partitions:</para>
625
626 <programlisting>&gt; mkfs.fat -F32 -nEFI /dev/sda1
627&gt; mkfs.ext4 -LROOT /dev/sda2
628&gt; mkfs.ext4 -LROOT /dev/sda3
629&gt; mkfs.ext4 -LROOT /dev/sda4
630&gt; mkfs.ext4 -LROOT /dev/sda5
631&gt; mkfs.ext4 -LROOT /dev/sda6
632&gt; mkfs.ext4 -LROOT /dev/sda7</programlisting>
633 </listitem>
634
635 <listitem>
636 <para>Create a GRUB partition:</para>
637
638 <programlisting>&gt; mkdir /mnt/boot
639&gt; mount /dev/sda1 /mnt/boot
640&gt; mkdir -p /mnt/boot/EFI/boot
641
642&gt; cp grub-efi-bootx64.efi /mnt/boot/EFI/boot/bootx64.efi
643&gt; vi /mnt/boot/EFI/boot/grub.cfg
644default=1
645
646menuentry "Linux Reference Image" {
647 linux (hd0,gpt2)/boot/bzImage root=/dev/sda2 ip=dhcp
648}
649
650menuentry "Linux sda3" {
651 linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp
652}
653
654menuentry "Linux sda4" {
655 linux (hd0,gpt4)/boot/bzImage root=/dev/sda4 ip=dhcp
656}
657
658menuentry "Linux sda5" {
659 linux (hd0,gpt5)/boot/bzImage root=/dev/sda5 ip=dhcp
660}
661
662menuentry "Linux sda6" {
663 linux (hd0,gpt6)/boot/bzImage root=/dev/sda6 ip=dhcp
664}
665
666menuentry "Linux sda7" {
667 linux (hd0,gpt7)/boot/bzImage root=/dev/sda7 ip=dhcp
668}</programlisting>
669 </listitem>
670 </orderedlist>
671 </section>
672
673 <section id="boot-hdd">
674 <title>Installing and booting Enea NFV Access on the harddisk</title>
675
676 <para>After partitioning the harddisk, boot Enea NFV Access from RAMFS
677 or from a reference image installed on one of the partitions.</para>
678
679 <para>To install Enea NFV Access image on a partition follow these
680 steps:</para>
681
682 <orderedlist>
683 <listitem>
684 <para>Copy your image on target:</para>
685
686 <programlisting>server&gt; scp ./enea-nfv-access-xeon-d.tar.gz /
687root@&lt;target_ip&gt;:/home/root/</programlisting>
688 </listitem>
689
690 <listitem>
691 <para>Extract image onto the desired partition:</para>
692
693 <programlisting>target&gt; mount /dev/sda3 /mnt/sda
694target&gt; tar -pzxf /home/root/enea-nfv-access-xeon-d.tar.gz /
695-C /mnt/sda</programlisting>
696
697 <para>Alternately, you can do both steps in one command from the
698 server:</para>
699
700 <programlisting>server&gt; cat ./enea-nfv-access-xeon-d.tar.gz | /
701ssh root@&lt;target_ip&gt; "cd /mnt/sda6; tar -zxf -"</programlisting>
702 </listitem>
703
704 <listitem>
705 <para>Reboot</para>
706 </listitem>
707
708 <listitem>
709 <para>From the GRUB menu select your partition</para>
710 </listitem>
711 </orderedlist>
712
713 <note>
714 <para>In order to change kernel boot parameters you need to mount the
715 GRUB partition (i.e. <literal>/dev/sda1</literal>) and change the
716 <literal>EFI/boot/grub.cfg</literal> file.</para>
717 </note>
718 </section>
719 </section>
720</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml b/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml
deleted file mode 100644
index 211de99..0000000
--- a/doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml
+++ /dev/null
@@ -1,2097 +0,0 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="getting_started_ucpe_manager">
3 <title>Getting Started with Enea uCPE Manager</title>
4
5 <section id="prereq_ucpe">
6 <title>Prerequisites</title>
7
8 <para>Listed below are the main generic prerequisites required so that the
9 uCPE Manager can be deployed on the host platform:</para>
10
11 <itemizedlist>
12 <listitem>
13 <para>A uCPE device with Enea NFV Access Run Time Platform
14 installed.</para>
15 </listitem>
16
17 <listitem>
18 <para>A machine running CentOS 7 with network access to the physical
19 device.</para>
20 </listitem>
21
22 <listitem>
23 <para>CPU, RAM and storage requirements for the uCPE Manager:</para>
24
25 <itemizedlist>
26 <listitem>
27 <para>For small-sized deployments (tens of devices):</para>
28
29 <itemizedlist spacing="compact">
30 <listitem>
31 <para>4 cores</para>
32 </listitem>
33
34 <listitem>
35 <para>16 GB RAM</para>
36 </listitem>
37
38 <listitem>
39 <para>300 GB hard-drive</para>
40 </listitem>
41 </itemizedlist>
42 </listitem>
43
44 <listitem>
45 <para>For mid-sized deployments (hundreds of devices):</para>
46
47 <itemizedlist spacing="compact">
48 <listitem>
49 <para>8 cores</para>
50 </listitem>
51
52 <listitem>
53 <para>32 GB RAM</para>
54 </listitem>
55
56 <listitem>
57 <para>300 GB hard-drive</para>
58 </listitem>
59 </itemizedlist>
60 </listitem>
61
62 <listitem>
63 <para>For large deployments (thousands of devices):</para>
64
65 <itemizedlist spacing="compact">
66 <listitem>
67 <para>16 cores</para>
68 </listitem>
69
70 <listitem>
71 <para>64-256 GB RAM</para>
72 </listitem>
73
74 <listitem>
75 <para>1 - 2 TB hard-drive</para>
76 </listitem>
77 </itemizedlist>
78 </listitem>
79 </itemizedlist>
80 </listitem>
81 </itemizedlist>
82 </section>
83
84 <section id="install_ucpe_manager">
85 <title>Install the Enea uCPE Manager</title>
86
87 <para>Unpack the uCPE Manager and install it following the instructions
88 below.</para>
89
90 <section id="prep_sys_ucpe_mg">
91 <title>Preparing your system</title>
92
93 <orderedlist>
94 <listitem>
95 <para>Install Java:</para>
96
97 <orderedlist>
98 <listitem>
99 <para>Install OpenJDK 11:</para>
100
101 <programlisting>sudo yum install java-11-openjdk-devel</programlisting>
102 </listitem>
103
104 <listitem>
105 <para>Verify the installation:</para>
106
107 <programlisting>java -version
108
109openjdk version "11.0.3" 2019-04-16 LTS
110OpenJDK Runtime Environment 18.9 (build 11.0.3+7-LTS)
111OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing)</programlisting>
112
113 <note>
114 <para>If there are multiple java versions installed, switch
115 between them using the following command:</para>
116
117 <programlisting>alternatives --config java</programlisting>
118
119 <para>Optionally, the user can switch between the javac versions using:
120 <literal>alternatives --config javac</literal>.</para>
121 </note>
122 </listitem>
123
124 <listitem>
125 <para>The following system variables need to point to the
126 OpenJDK 11 installation:</para>
127
128 <programlisting>export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which java)))))
129export PATH=$PATH:$JAVA_HOME/bin
130export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar</programlisting>
131
132 <note>
133 <para>In order to make these system variables persistent, the commands given above
134 should be added to a script in the <literal>/etc/profile.d/</literal> folder.
135 <emphasis role="bold">Sudo</emphasis> access is needed for this operation.</para>
136 </note>
137 </listitem>
138 </orderedlist>
139 </listitem>
140
141 <listitem>
142 <para>Open a terminal with administrative rights, i.e. log into a
143 <emphasis role="bold">bash</emphasis> shell with
144 <literal>root</literal> privileges.</para>
145 </listitem>
146
147 <listitem>
148 <para>If you plan to use the PostgreSQL server bundled with the uCPE
149 Manager, verify that there is no existing installation of the
150 Postgres database. Execute the following command to check if you
151 have a currently running PostgreSQL database server:</para>
152
153 <programlisting>ps -ef | grep post</programlisting>
154
155 <para>To remove a currently installed PostgreSQL server (including
156 the existing postgres user), run the following commands:</para>
157
158 <programlisting>yum remove postgres\*
159rm -f /var/lib/pgsql
160rm -f /etc/postgres-reg.ini
161userdel postgres</programlisting>
162
163 <note>
164 <para>This step is not necessary if the uCPE Manager will be using
165 an external database (like MariaDB).</para>
166 </note>
167 </listitem>
168
169 <listitem>
170 <para>Choose the target installation folder, e.g.
171 <literal>/opt/ems</literal>. Everything will be installed under a
172 folder called <literal>ucpemanager</literal> within the target
173 installation folder.</para>
174
175 <para>The application files will be installed in the
176 <literal>/opt/ems/ucpemanager/application</literal> folder, while the database
177 will be installed in the <literal>/opt/ems/ucpemanager/database</literal> folder.</para>
178 </listitem>
179 </orderedlist>
180
181 <note>
182 <para>If you have multiple spindles, it is recommended to let the
183 application run off one and the database off the other. This will
184 result in optimum performance. It is also recommended that the swap
185 disk be the same as the one used for the application.</para>
186
187 <para>Assuming another spindle is used (<literal>/drive2</literal>) do
188 the following:</para>
189
190 <orderedlist>
191 <listitem>
192 <para>Create a folder which will host the database (e.g.
193 <literal>emsDatabase</literal>).</para>
194 </listitem>
195
196 <listitem>
197 <para>Create a soft-link that will point to this folder:</para>
198
199 <programlisting>ln -s /opt/ems/elementcenter/database /drive2/emsDatabase</programlisting>
200 </listitem>
201
202 <listitem>
203 <para>Follow the installation process as described below.</para>
204 </listitem>
205 </orderedlist>
206 </note>
207 </section>
208
209 <section id="installing_ucpe_mg">
210 <title>Installing the uCPE Manager</title>
211
212 <orderedlist>
213 <listitem>
214 <para>Open a terminal with administrative rights, i.e. log into a
215 <emphasis role="bold">bash</emphasis> shell with
216 <literal>root</literal> privileges.</para>
217 </listitem>
218
219 <listitem>
220 <para><command>cd</command> to the folder you are installing
221 from.</para>
222 </listitem>
223
224 <listitem>
225 <para>Verify that the folder you are installing from contains the
226 following files:</para>
227
228 <itemizedlist>
229 <listitem>
230 <para><filename>README</filename></para>
231 </listitem>
232
233 <listitem>
234 <para><filename>install.sh</filename></para>
235 </listitem>
236
237 <listitem>
238 <para><filename>doinstall.sh</filename></para>
239 </listitem>
240
241 <listitem>
242 <para><filename>configureHA.sh</filename></para>
243 </listitem>
244
245 <listitem>
246 <para><filename>Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename></para>
247 </listitem>
248
249 <listitem>
250 <para><filename>doc/ReleaseNotes</filename></para>
251 </listitem>
252 </itemizedlist>
253 </listitem>
254
255 <listitem>
256 <para>Run the following command:</para>
257
258 <programlisting>./install.sh /opt/ems \
259 Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
260 </listitem>
261 </orderedlist>
262
263 <para>This command will:</para>
264
265 <itemizedlist>
266 <listitem>
267 <para>Extract the application files from the compressed install
268 kit.</para>
269 </listitem>
270
271 <listitem>
272 <para>Install the bundled database (if the user specifies an
273 internal database).</para>
274 </listitem>
275
276 <listitem>
277 <para>Install <literal>ucpemanager</literal> as a service with the
278 name <filename>ucpemanager</filename>.</para>
279 </listitem>
280
281 <listitem>
282 <para>Start the <literal>ucpemanager</literal> service.</para>
283 </listitem>
284 </itemizedlist>
285
286 <note>
287 <para>The service will be automatically started when the computer
288 boots up. The user may enable the firewall in order to allow access to
289 these specific ports: 80 (TCP), 443 (TCP), 54327 (UDP), 5701:5708
290 (TCP) and 7000:7009 (TCP). If callhome is used, access to the
291 following ports must also be allowed: 4334 (TCP) and 2021:2040 (TCP).
292 Otherwise, the user should check that the CentOS machine where the
293 uCPE Manager is installed has the firewall disabled.</para>
294 </note>
295
296 <para>Verify that the installation has succeeded by:</para>
297
298 <orderedlist>
299 <listitem>
300 <para>Pointing your browser to the server machine running the uCPE
301 Manager.</para>
302 </listitem>
303
304 <listitem>
305 <para>In the login screen, log in with the username: <emphasis
306 role="bold">admin</emphasis> and password: <emphasis
307 role="bold">admin</emphasis>.</para>
308 </listitem>
309 </orderedlist>
310
311 <para>In order to manage the ucpemanager service, user can run:
312 <programlisting>service ucpemanager start/stop</programlisting></para>
313 </section>
314
315 <section id="ins_restore_option">
316 <title>Installing with the restore option</title>
317
318 <para>It is possible to use a restore file created by the "System
319 Backup" utility provided in the uCPE Manager, to install a system and
320 set it to a known state.</para>
321
322 <note>
323 <para>The file to be used is the zip file created by System Backup,
324 not the one created by the uninstall or upgrade processes described
325 below.</para>
326 </note>
327
328 <para>The name format of this file will be:
329 <filename>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</filename> (e.g
330 <literal>SystemBackup_Feb19_2013_2257_42.zip</literal>).</para>
331
332 <para>Follow the steps for Installation provided above and provide an
333 additional argument as shown below:</para>
334
335 <programlisting>./install.sh \
336 /opt/ems Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz \
337 SystemBackup_MMMDD_YYYY_HHMM_SS.zip</programlisting>
338
339 <para>The other steps are exactly the same as specified in the
340 Installation instructions.</para>
341 </section>
342
343 <section id="upgrading_ucpe_mg">
344 <title>Upgrading the uCPE Manager</title>
345
346 <orderedlist>
347 <listitem>
348 <para>Verify that the folder you are upgrading from contains the
349 following files:</para>
350
351 <itemizedlist>
352 <listitem>
353 <para><filename>upgrade.sh</filename></para>
354 </listitem>
355
356 <listitem>
357 <para><filename>doupgrade.sh</filename></para>
358 </listitem>
359
360 <listitem>
361 <para><filename>configureHA.sh</filename></para>
362 </listitem>
363
364 <listitem>
365 <para><filename>Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename></para>
366 </listitem>
367 </itemizedlist>
368 </listitem>
369
370 <listitem>
371 <para>Run the following command:</para>
372
373 <programlisting>./upgrade.sh /opt/ems \
374 Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
375 </listitem>
376 </orderedlist>
377
378 <para>Running this command will:</para>
379
380 <itemizedlist>
381 <listitem>
382 <para>Stop the currently running ucpemanager service.</para>
383 </listitem>
384
385 <listitem>
386 <para>Create a compressed file of the ucpemanager application
387 folder, called:
388 <literal>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</literal>, which
389 contains a snapshot of the existing installation.</para>
390 </listitem>
391
392 <listitem>
393 <para>Rename the <literal>application</literal> folder to
394 <literal>application_original</literal>.</para>
395 </listitem>
396
397 <listitem>
398 <para>Extract the application files from the specified compressed
399 install kit. There will now exist a (new) application folder, with
400 the contents of the new kit.</para>
401 </listitem>
402
403 <listitem>
404 <para>Start the ucpemanager service.</para>
405 </listitem>
406 </itemizedlist>
407
408 <para>When the ucpemanager service starts, it will recognize the fact
409 that an old version of the application needs to be upgraded (based upon
410 the existence of the <literal>application_original</literal> folder. All
411 the relevant data from the old installation will be copied to the new
412 one and the <literal>application_original</literal> folder will be
413 deleted.</para>
414 </section>
415
416 <section id="uninstalling_ucpe_mg">
417 <title>Uninstalling an existing uCPE Manager installation</title>
418
419 <orderedlist>
420 <listitem>
421 <para>Verify that the folder you are uninstalling from contains the
422 following files:</para>
423
424 <itemizedlist>
425 <listitem>
426 <para><filename>uninstall.sh</filename></para>
427 </listitem>
428
429 <listitem>
430 <para><filename>douninstall.sh</filename></para>
431 </listitem>
432 </itemizedlist>
433 </listitem>
434
435 <listitem>
436 <para>Run the following command:</para>
437
438 <programlisting>./uninstall.sh /opt/ems</programlisting>
439 </listitem>
440 </orderedlist>
441
442 <para>Running this command will:</para>
443
444 <itemizedlist>
445 <listitem>
446 <para>Stop the currently running ucpemanager service.</para>
447 </listitem>
448
449 <listitem>
450 <para>Create a compressed file of the ucpemanager application
451 folder, called
452 <literal>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</literal>, which
453 contains a snapshot of the existing installation.</para>
454 </listitem>
455
456 <listitem>
457 <para>Uninstall the ucpemanager service, so that it will not startup
458 on reboot.</para>
459 </listitem>
460
461 <listitem>
462 <para>Uninstall the database service (if an internal database is
463 being used).</para>
464 </listitem>
465
466 <listitem>
467 <para>Completely remove the contents of the
468 <literal>application</literal> and <literal>database</literal>
469 folders.</para>
470 </listitem>
471 </itemizedlist>
472
473 <para>After these steps, the uCPE Manager is completely removed from the
474 system.</para>
475 </section>
476
477 <section id="restoring_pre_installation">
478 <title>Restoring a previous uCPE Manager installation</title>
479
480 <orderedlist>
481 <listitem>
482 <para>Verify that the folder you are restoring from contains the
483 following files:</para>
484
485 <itemizedlist>
486 <listitem>
487 <para><filename>restore.sh</filename></para>
488 </listitem>
489
490 <listitem>
491 <para><filename>dorestore.sh</filename></para>
492 </listitem>
493
494 <listitem>
495 <para><filename>configureHA.sh</filename></para>
496 </listitem>
497
498 <listitem>
499 <para><filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>
500 (the original installation snapshot, as obtained from a previous
501 uninstall).</para>
502 </listitem>
503 </itemizedlist>
504 </listitem>
505
506 <listitem>
507 <para>Run the following command:</para>
508
509 <programlisting>./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz</programlisting>
510 </listitem>
511 </orderedlist>
512
513 <para>Running this command will remove any vestiges of the existing
514 ucpemanager service, if they exist, and reinstall the ucpemanager
515 application on the specified target, restoring the data in the database
516 and files in the process.</para>
517
518 <para>The ucpemanager service is then started and the older version is
519 now running on the system.</para>
520 </section>
521 </section>
522
523 <section id="device_config_provision">
524 <title>Device Configuration and Provisioning</title>
525
526 <para>The following describes the steps required for setting up the
527 virtualization infrastructure, ensuring that a uCPE device is ready for
528 virtualized service deployment. The sections herein contain information
529 about enrolling uCPE devices into the Enea uCPE Manager, selecting
530 physical interfaces to be used by virtualized networking and creating
531 different types of bridges to enable VNF communication. The Zero Touch
532 Provisioning mechanism is also touched upon, as alternative to manual
533 configuration of the virtualization infrastructure.</para>
534
535 <section id="device_config">
536 <title>Add a uCPE device to the Management System</title>
537
538 <para>Enrolling uCPE devices into the Enea uCPE Manager can be
539 accomplished using one of the two possible methods.</para>
540
541 <section id="man_config">
542 <title>Direct Connection</title>
543
544 <para>When using this mechanism, the uCPE Manager will periodically
545 poll the uCPE device, using a specified IP address as the destination,
546 attempting to establish a management connection.</para>
547
548 <para>Add the uCPE device running the NFV Access Run Time Platform to
549 the management system by:</para>
550
551 <orderedlist>
552 <listitem>
553 <para>Selecting in the uCPE Manager: <literal>Devices -&gt; Manage
554 -&gt; Add</literal>.</para>
555 </listitem>
556
557 <listitem>
558 <para>Suppling information about the uCPE device, and setting the
559 parameters that will be used to connect to it.</para>
560 </listitem>
561 </orderedlist>
562
563 <para>The relevant parameters are:</para>
564
565 <itemizedlist>
566 <listitem>
567 <para>Type. The type of device to be added, i.e <literal>Enea
568 universal CPE</literal>.</para>
569 </listitem>
570
571 <listitem>
572 <para>Name. The name by which the device is referred to in the
573 uCPE Manager.</para>
574 </listitem>
575
576 <listitem>
577 <para>SSH Port. The NETCONF Port used for communications. Default
578 is set to 830.</para>
579 </listitem>
580
581 <listitem>
582 <para>SSH User Name. The user name for SSH connectivity. Default
583 user is root.</para>
584 </listitem>
585
586 <listitem>
587 <para>SSH Password. Leave this blank.</para>
588 </listitem>
589
590 <listitem>
591 <para>Device Calls Home. This checkbox indicates the direction of
592 device communications. For Direct Connection, leave this flag
593 unchecked.</para>
594 </listitem>
595
596 <listitem>
597 <para>Device ID. The unique identifier of the uCPE device.</para>
598 </listitem>
599 </itemizedlist>
600 </section>
601
602 <section id="using_call_home">
603 <title>Device Call Home Connection</title>
604
605 <para>Follow the same steps as described in the previous section,
606 making sure that the <literal>Device Calls Home</literal> checkbox is
607 selected this time.</para>
608
609 <para>When using this mechanism, the device will initiate a connection
610 to the uCPE Manager for NETCONF traffic (over SSH), while the uCPE
611 Manager waits for a device connection. For more information please see
612 section <olink targetdoc="book_enea_nfv_access_getting_started"
613 targetptr="auto_installer">Creating a bootable USB stick in the
614 <xi:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
615 xmlns:xi="http://www.w3.org/2001/XInclude"
616 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
617 Manual for more details.</para>
618 </section>
619 </section>
620
621 <section id="host_int_net_config">
622 <title>Configure NFV Infrastructure</title>
623
624 <para>Once a management connection with the uCPE device has been
625 established by using any of the supported methods, the virtualization
626 networking infrastructure can be configured either manually or by using
627 Zero Touch Provisioning.</para>
628
629 <para>Available network interfaces can be added to the management
630 system, for use by the networking virtualization infrastructure.</para>
631
632 <para>In order to make physical network interfaces available to the
633 virtualization infrastructure and VNFs, they must be configured into the
634 management system.</para>
635
636 <para>To add an interface into the uCPE Manager, select the uCPE device,
637 then from the top toolbar select <literal>Configuration -&gt; External
638 Interfaces -&gt; Configuration -&gt; Add</literal>. The available
639 Interface types are detailed below.</para>
640
641 <section id="dpdk_interface_type">
642 <title>DPDK Interface Type</title>
643
644 <para>Configuring a physical interface in DPDK mode will require a
645 DPDK-based application (e.g. OVS-DPDK) in order to access and use the
646 interface. An interface set as DPDK can be attached to an OVS-DPDK
647 bridge.</para>
648
649 <note>
650 <para>Make sure the <literal>Enable DPDK</literal> checkbox is
651 selected in <literal>Device -&gt; Configuration -&gt;
652 DPDK</literal>, otherwise no interface can be assigned as
653 DPDK.</para>
654 </note>
655
656 <para>To add a DPDK interface under the management system, set
657 appropriate values for the following fields:</para>
658
659 <itemizedlist>
660 <listitem>
661 <para>Source: name of the physical interface.</para>
662 </listitem>
663
664 <listitem>
665 <para>Type: dpdk</para>
666 </listitem>
667
668 <listitem>
669 <para>Networking-type: dpdk</para>
670 </listitem>
671
672 <listitem>
673 <para>Dpdk-type: the kernel module that allows user space access
674 to the physical interface. Either the <literal>vfio-pci</literal>
675 or the <literal>igb_uio</literal> driver can be used.</para>
676 </listitem>
677 </itemizedlist>
678 </section>
679
680 <section id="sriov_interface_type">
681 <title>SR-IOV Interface Type</title>
682
683 <para>SR-IOV technology allows for the creation of a number of virtual
684 functions on the host interface, which can be used by VNFs running on
685 the uCPE device.</para>
686
687 <para>For SR-IOV mode configuration, the user must set values for the
688 following fields:</para>
689
690 <itemizedlist>
691 <listitem>
692 <para>Source: name of the physical interface.</para>
693 </listitem>
694
695 <listitem>
696 <para>Type: sr-iov</para>
697 </listitem>
698
699 <listitem>
700 <para>Networking-type: srIov</para>
701 </listitem>
702
703 <listitem>
704 <para>sriov-mode: adapter-pool</para>
705 </listitem>
706
707 <listitem>
708 <para>sriov-num-vfs: the number of virtual functions to
709 create.</para>
710 </listitem>
711 </itemizedlist>
712 </section>
713
714 <section id="standard_interface_type">
715 <title>Standard Interface Type</title>
716
717 <para>Some of the physical network interfaces available on a uCPE
718 device, including Ethernet interfaces, do not have DPDK or SR-IOV
719 support. Instead, the Linux kernel driver has to be used. Wi-Fi and
720 4G/LTE modems can also be configured and used for virtualization
721 infrastructure and VNFs.</para>
722
723 <para>To add Standard interfaces under the management system, the user
724 must set values for the following fields:</para>
725
726 <itemizedlist>
727 <listitem>
728 <para>Source: the name of physical interface.</para>
729 </listitem>
730
731 <listitem>
732 <para>Networking-type: standard</para>
733 </listitem>
734 </itemizedlist>
735 </section>
736
737 <section condition="hidden" id="pci_passthrough_interface_type">
738 <title>PCI Passthrough Interface Type</title>
739
740 <para>For the PCI Passthrough a user does not have to configure a
741 physical interface, instead simply select the PCI address and connect
742 it to a virtual port when the VNF instantiation step is
743 reached.</para>
744 </section>
745
746 <section id="man_configuration">
747 <title>Manual Configuration</title>
748
749 <para>For Manual Configuration of uCPE networking, select the uCPE
750 device first and then <literal>Configuration</literal> -&gt;
751 <literal>External Interfaces</literal>, where one can find a list of
752 available network interfaces and their capabilities.</para>
753
754 <section id="configure_interfaces">
755 <title>Configuring Interfaces</title>
756
757 <para>After networking interfaces have been added to the uCPE
758 Manager, the user can change the interface type (DPDK, SR-IOV,
759 Standard, WAN).</para>
760
761 <note>
762 <para>WAN interfaces, which are configured during the installation
763 of the device, do not need to be added, they will be automatically
764 listed as such in the uCPE manager when the device
765 connects.</para>
766 </note>
767
768 <figure>
769 <title>Configuration of External Interfaces</title>
770
771 <mediaobject>
772 <imageobject>
773 <imagedata align="center" contentwidth="600"
774 fileref="images/edit_inter_config.png" />
775 </imageobject>
776 </mediaobject>
777 </figure>
778
779 <para><emphasis role="bold">How to Edit the Configuration of an
780 Interface</emphasis></para>
781
782 <orderedlist>
783 <listitem>
784 <para>To edit an interface configuration type from the uCPE
785 Manager, select the uCPE device, then from the top toolbar
786 select the <literal>Configuration</literal> menu then
787 <literal>External Interfaces -&gt; Configuration</literal>. The
788 already configured interfaces are displayed here, as can be seen
789 in the figure above.</para>
790 </listitem>
791
792 <listitem>
793 <para>In order to edit an already configured interface, (as in
794 the example popup shown below, a WAN interface) double click on
795 the desired one and a popup will appear. A different popup
796 appears for each type of interface. From the Host Interface
797 window, a user can change the networking type and the IP address
798 assignment:</para>
799
800 <figure>
801 <title>Editing an Interface</title>
802
803 <mediaobject>
804 <imageobject>
805 <imagedata align="center" contentwidth="500"
806 fileref="images/edit_inter.png" />
807 </imageobject>
808 </mediaobject>
809 </figure>
810 </listitem>
811 </orderedlist>
812
813 <note>
814 <para>The IP address assignment of an interface can be set as
815 static or dynamic for each type of interface.</para>
816 </note>
817 </section>
818
819 <section id="configure_bridges">
820 <title>Configuring Bridges</title>
821
822 <para>After networking interfaces have been added to the uCPE
823 Manager, the user can create the necessary OVS bridges.</para>
824
825 <figure>
826 <title>OVS Bridges</title>
827
828 <mediaobject>
829 <imageobject>
830 <imagedata align="center" contentwidth="600"
831 fileref="images/ovs_bridges_tab.png" />
832 </imageobject>
833 </mediaobject>
834 </figure>
835
836 <para><emphasis role="bold">How to add OVS bridges in the uCPE
837 Manager</emphasis></para>
838
839 <orderedlist>
840 <listitem>
841 <para>Select the uCPE device.</para>
842 </listitem>
843
844 <listitem>
845 <para>Select Configuration.</para>
846 </listitem>
847
848 <listitem>
849 <para>Click OpenvSwitch.</para>
850 </listitem>
851
852 <listitem>
853 <para>Select the Bridges option, then click Add.</para>
854 </listitem>
855 </orderedlist>
856
857 <note>
858 <para>Depending on the settings in <literal>Configuration -&gt;
859 OpenVSwitch -&gt; DPDK</literal>, OVS bridges with or without DPDK
860 support will be used on the uCPE device.</para>
861 </note>
862
863 <para>There are three types of bridges which can be created, each
864 one fulfiling a different role.</para>
865
866 <section id="inband_mg_bridge">
867 <title>uCPE In-band Management bridge</title>
868
869 <para>In-band Management refers to a model where both the data
870 plane and control plane flow over the same network path. In some
871 situations (e.g. the uCPE device has only one routable IP
872 address), this is the only option available to both control and
873 configure the uCPE device, while also allowing for data-path
874 traffic to pass over the same physical interface.</para>
875
876 <para>The solution provided by Enea for in-band management is
877 based upon an OpenvSwitch bridge fielding all traffic passing
878 through the WAN physical port. Any standard or DPDK-assigned
879 network interface can be used for the In-Band management
880 bridge.</para>
881
882 <note>
883 <para>The In-Band Management bridge must be recreated each time
884 the uCPE Manager IP address is changed.</para>
885 </note>
886
887 <para>To create the In-Band Management bridge, the user must set
888 values for the following fields:</para>
889
890 <itemizedlist>
891 <listitem>
892 <para>name: name of the bridge.</para>
893 </listitem>
894
895 <listitem>
896 <para>ovs-bridge-type: inbandMgmt</para>
897 </listitem>
898 </itemizedlist>
899
900 <note>
901 <para>The first VNF instantiated on the uCPE device must be
902 connected to the In-Band Management bridge and its WAN interface
903 must be configured as the DHCP client.</para>
904 </note>
905 </section>
906
907 <section id="inband_mg_br_vnfs">
908 <title>In-band Management bridge for VNFs</title>
909
910 <para>If VNF management can be done over a dedicated virtual
911 interface, its possible to extend the networking infrastructure
912 configuration to also access the VNF's management interface over
913 the WAN port.</para>
914
915 <para>For this setup, three types of traffic will pass over the
916 WAN physical interface:</para>
917
918 <itemizedlist>
919 <listitem>
920 <para>Device management. Part of the device configuration done
921 by the uCPE Manager.</para>
922 </listitem>
923
924 <listitem>
925 <para>VNF(s) management. Enabling or disabling features of a
926 VNF. E.g. enabling/disabling the firewall or VPN setup.</para>
927 </listitem>
928
929 <listitem>
930 <para>Data-path. All other traffic that is not used in the
931 control plane and needs to reach a LAN network.</para>
932 </listitem>
933 </itemizedlist>
934
935 <para>To create a VNF In-Band Management bridge, the user must set
936 values for the following fields:</para>
937
938 <itemizedlist>
939 <listitem>
940 <para>name: name of the bridge.</para>
941 </listitem>
942
943 <listitem>
944 <para>ovs-bridge-type: vnfMgmt</para>
945 </listitem>
946
947 <listitem>
948 <para>vnf-mgmt-address: select IPv4 as the type and fill in
949 the IP address for management network, e.g 10.0.0.1.</para>
950 </listitem>
951 </itemizedlist>
952
953 <note>
954 <para>VNF management interfaces must be configured in same
955 network as the <literal>vnf-mgmt-address</literal> of the
956 bridge. For more information, please see section <olink
957 targetdoc="book_enea_nfv_access_getting_started"
958 targetptr="vnf_management">VNF Management in the <xi:include
959 href="../../s_docbuild/olinkdb/pardoc-names.xml"
960 xmlns:xi="http://www.w3.org/2001/XInclude"
961 xpointer="element(book_enea_nfv_access_getting_started/1)" /></olink>
962 Manual.</para>
963 </note>
964 </section>
965
966 <section id="dataplane_bridge">
967 <title>Data-plane Bridge</title>
968
969 <para>Data-plane bridges are generic bridges used for the VNF
970 data-plane. There are two supported sub-types:</para>
971
972 <itemizedlist>
973 <listitem>
974 <para>communication: allows for VNF communication towards
975 LAN/WAN networks. This bridge type has at least one physical
976 port attached to it.</para>
977 </listitem>
978
979 <listitem>
980 <para>integration: allows for VNF-to-VNF communication
981 (usually for service function chaining). This bridge type does
982 not have any physical port attached.</para>
983 </listitem>
984 </itemizedlist>
985
986 <para>To create a Data-plane bridge, the user must set values for
987 the following fields:</para>
988
989 <itemizedlist>
990 <listitem>
991 <para>name: name of the bridge.</para>
992 </listitem>
993
994 <listitem>
995 <para>ovs-bridge-type: select <literal>communication</literal>
996 or <literal>integration</literal>, depending on intended
997 usage. For communication bridges, physical interfaces can be
998 added to the bridge.</para>
999 </listitem>
1000 </itemizedlist>
1001 </section>
1002 </section>
1003 </section>
1004
1005 <section id="zero_touch_prov">
1006 <title>Zero Touch Provisioning</title>
1007
1008 <para>Zero-Touch Provisioning (ZTP) refers to the process of when a
1009 device starts up for the first time and its initial configuration is
1010 pushed down by an external management system, so that it is setup for
1011 proper operation without additional manual intervention by an
1012 operator. ZTP is an alternative to Manual configuration.</para>
1013
1014 <para>A variety of operations can occur as part of ZTP such as initial
1015 device setup, configuration of managed objects, etc. The goal is to
1016 set up a device to the maximum possible extent without forcing an
1017 operator to be physically present (initially) to manage the
1018 device.</para>
1019
1020 <para>An offline configuration is usually prepared in advance for the
1021 uCPE Manager to setup the virtualization infrastructure on the uCPE
1022 device, as soon as a device enrolls into the management system.</para>
1023
1024 <section id="offline_configuration">
1025 <title>Offline Configuration</title>
1026
1027 <para>The Offline Configuration subsystem is used to pre-populate a
1028 configuration for a device that will be brought under management at
1029 a future point in time. When creating an offline configuration store
1030 a <literal>Device ID</literal> can be specified. This ID uniquely
1031 identifies the device to be initialized.</para>
1032
1033 <para>Alternatively, a wildcard can be used in the <literal>Device
1034 ID</literal> field, which results in a configuration being pushed on
1035 all uCPE devices upon their initial connection towards the uCPE
1036 Manager.</para>
1037
1038 <para>To create an offline configuration, from the top toolbar menu
1039 select <literal>Applications</literal> -&gt; <literal>Offline
1040 Config</literal> -&gt; <literal>Add</literal>. The following fields
1041 are available:</para>
1042
1043 <itemizedlist>
1044 <listitem>
1045 <para>Name: name of the device.</para>
1046 </listitem>
1047
1048 <listitem>
1049 <para>Device type: Enea universal CPE.</para>
1050 </listitem>
1051
1052 <listitem>
1053 <para>Device version: 2.2.2</para>
1054 </listitem>
1055
1056 <listitem>
1057 <para>Config Set: uCPE Config</para>
1058 </listitem>
1059
1060 <listitem>
1061 <para>Device ID: device ID or a wildcard(*).</para>
1062 </listitem>
1063
1064 <listitem>
1065 <para>Device Grouping Tags: a tag to group devices. These tags
1066 match the customer tags provided during the installation of the
1067 device.</para>
1068 </listitem>
1069 </itemizedlist>
1070
1071 <para>When a device connects to the uCPE Manager for the first time,
1072 it checks the device to see if it has been Zero Touch Provisioned
1073 (ZTP). If not, it looks for an offline configuration that matches
1074 these values, in the following order:</para>
1075
1076 <itemizedlist>
1077 <listitem>
1078 <para>The Device ID.</para>
1079 </listitem>
1080
1081 <listitem>
1082 <para>The set of tags.</para>
1083 </listitem>
1084
1085 <listitem>
1086 <para>A "*" for Device ID (wildcard).</para>
1087 </listitem>
1088 </itemizedlist>
1089
1090 <para>If a match is found, the offline configuration is sent to the
1091 device as part of Zero-Touch-Provisioning.</para>
1092
1093 <para>After creating the Offline Config Store, access the device
1094 through <literal>Applications</literal> -&gt; <literal>offline
1095 config</literal> -&gt; <literal>Config App</literal> and provision
1096 it with the required initial configuration. This operation mirrors
1097 what happens during manual configuration described in the previous
1098 section.</para>
1099 </section>
1100 </section>
1101
1102 <section id="custom_scripts">
1103 <title>Custom Scripts</title>
1104
1105 <para>The custom scripts feature allows users to execute user-defined
1106 scripts on the uCPE device at various times.This allows for more
1107 flexible and advanced configurations such as a LTE modem
1108 configuration, advanced network configurations or OVS flow rule
1109 programming at any time.</para>
1110
1111 <section id="upload_scripts">
1112 <title>Uploading Scripts</title>
1113
1114 <para>The scripts need to be uploaded to the uCPE Manager prior to
1115 use. When uploading scripts to the uCPE Manager make sure to select
1116 the right script type.</para>
1117
1118 <para>The following script types are supported:</para>
1119
1120 <itemizedlist>
1121 <listitem>
1122 <para><literal>Once-before-startup</literal>. This script will
1123 only execute once during the startup.</para>
1124 </listitem>
1125
1126 <listitem>
1127 <para><literal>Always-before-startup</literal>. This script will
1128 always execute during the startup.</para>
1129 </listitem>
1130
1131 <listitem>
1132 <para><literal>Once-after-startup</literal>. This script will
1133 only execute once after the system has been started.</para>
1134 </listitem>
1135
1136 <listitem>
1137 <para><literal>Always-after-startup</literal>. This script will
1138 always execute after the system has been started.</para>
1139 </listitem>
1140 </itemizedlist>
1141
1142 <para>Follow the instruction below to upload scripts:</para>
1143
1144 <orderedlist>
1145 <listitem>
1146 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
1147 Scripts</literal> -&gt; <literal>Configure</literal>.</para>
1148 </listitem>
1149
1150 <listitem>
1151 <para>Select <literal>Upload to EMS</literal>.</para>
1152 </listitem>
1153
1154 <listitem>
1155 <para>In the <literal>Script Type</literal> menu, select the
1156 type the uploaded script should have.</para>
1157 </listitem>
1158
1159 <listitem>
1160 <para>Press <literal>Choose File</literal> to select the scripts
1161 needed, and then press <literal>Send</literal>.</para>
1162 </listitem>
1163 </orderedlist>
1164 </section>
1165
1166 <section id="remove_scripts">
1167 <title>Removing Scripts</title>
1168
1169 <para>Follow the instruction below to remove scripts:</para>
1170
1171 <orderedlist>
1172 <listitem>
1173 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
1174 Scripts</literal> -&gt; <literal>Configure</literal>.</para>
1175 </listitem>
1176
1177 <listitem>
1178 <para>Select the script you want to delete from the
1179 <literal>Uploaded Scripts</literal> tab and then click
1180 <literal>Delete</literal>, which will remove the script
1181 immediately from the uCPE Manager.</para>
1182 </listitem>
1183 </orderedlist>
1184 </section>
1185
1186 <section id="configure_scripts">
1187 <title>Configuring Script Location</title>
1188
1189 <para>The location where the scripts are staged in the uCPE Manager
1190 can be chanaged as described below:</para>
1191
1192 <orderedlist>
1193 <listitem>
1194 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
1195 Scripts</literal> -&gt; <literal>Configure</literal>.</para>
1196 </listitem>
1197
1198 <listitem>
1199 <para>Select the <literal>Configuration</literal> tab and
1200 specify a new loacation to store the scripts.</para>
1201
1202 <note>
1203 <para>Change the script storage location only if you have many
1204 scripts which you would prefer to store on another partition,
1205 otherwise leave this configuration as is.</para>
1206 </note>
1207 </listitem>
1208 </orderedlist>
1209 </section>
1210
1211 <section id="run_the_scripts">
1212 <title>Running the Scripts</title>
1213
1214 <para><emphasis role="bold">How to run Custom
1215 Scripts</emphasis></para>
1216
1217 <orderedlist>
1218 <listitem>
1219 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
1220 Scripts</literal> -&gt; <literal>Apply Scripts</literal>.</para>
1221 </listitem>
1222
1223 <listitem>
1224 <para>In the <literal>Script Config Screen</literal> pop up,
1225 select the devices from the device(s) chooser list on which to
1226 run the scripts. Press the <literal>&gt;</literal> button to
1227 move the devices to the right side of the chooser, which is the
1228 list of devices that will execute the selected scripts.</para>
1229 </listitem>
1230
1231 <listitem>
1232 <para>Select the scripts from the list under the device(s)
1233 chooser by pressing the <literal>+</literal> button.</para>
1234 </listitem>
1235
1236 <listitem>
1237 <para>In the pop-up window, select the scripts from the list. If
1238 there are no scripts to select, then there is no script uploaded
1239 with that particular type. Upload the script(s) needed and try
1240 again.</para>
1241 </listitem>
1242
1243 <listitem>
1244 <para>Check the checkbox <literal>Reboot devices</literal> if
1245 you want to reboot and execute the scripts at once and then
1246 press <literal>ok</literal>.</para>
1247
1248 <note>
1249 <para>The status of execution for the scripts can be seen by
1250 opening the <literal>Fault</literal> -&gt;
1251 <literal>Events</literal> screen and filtering by device
1252 and/or the event name <filename>Custom</filename>.</para>
1253 </note>
1254 </listitem>
1255 </orderedlist>
1256 </section>
1257 </section>
1258 </section>
1259 </section>
1260
1261 <section id="device_upgrade">
1262 <title>Device Upgrade</title>
1263
1264 <section id="device_upgrade_process">
1265 <title>Device Upgrade Process</title>
1266
1267 <para>Device Upgrade/Install performs the following operations to the
1268 device:</para>
1269
1270 <itemizedlist>
1271 <listitem>
1272 <para><emphasis role="bold">Prepare for upgrade</emphasis>. This
1273 stage tells the device that an upgrade is about to happen.</para>
1274 </listitem>
1275
1276 <listitem>
1277 <para><emphasis role="bold">Install file on device</emphasis>. This
1278 stage copies the file to the uCPE device.</para>
1279 </listitem>
1280
1281 <listitem>
1282 <para><emphasis role="bold">Upgrade Device</emphasis>. This stage
1283 causes the device to replace its running image with the newly copied
1284 image.</para>
1285 </listitem>
1286 </itemizedlist>
1287 </section>
1288
1289 <section id="managing_device_upgrade">
1290 <title>Managing the Device Upgrade</title>
1291
1292 <para>Before an install or upgrade can be completed, certain
1293 configuration data must be set. Files also need to be uploaded to the
1294 Device Upgrade image repository in order to be uploaded to the
1295 device.</para>
1296
1297 <para>Launch the Device Upgrade management console by selecting
1298 <literal>Devices</literal> -&gt; <literal>Upgrade</literal> from the top
1299 toolbar. The console when launched will contain the following
1300 tabs:</para>
1301
1302 <itemizedlist>
1303 <listitem>
1304 <para><literal>Image Library</literal>. To add/delete an
1305 image.</para>
1306 </listitem>
1307
1308 <listitem>
1309 <para><literal>Upgrade Operations</literal>. See running upgrades,
1310 cancel any upgrades in progress, start a device upgrade.</para>
1311 </listitem>
1312
1313 <listitem>
1314 <para><literal>Configuration</literal>. Upgrade configuration
1315 parameters.</para>
1316 </listitem>
1317 </itemizedlist>
1318
1319 <para>Press <literal>Close</literal> when the message <literal>File
1320 Uploaded Successfully</literal> appears on the File Upload
1321 Screen.</para>
1322
1323 <note>
1324 <para>The image file of type <literal>rootfs.ostree.tar.bz2</literal>
1325 is available in the
1326 Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz
1327 file you downloaded with your release.</para>
1328 </note>
1329
1330 <section id="upload_image">
1331 <title>Image Library</title>
1332
1333 <para><emphasis role="bold">Add an image to the image
1334 repository/library</emphasis></para>
1335
1336 <orderedlist>
1337 <listitem>
1338 <para>Select <literal>Devices</literal> -&gt;
1339 <literal>Upgrade</literal>.</para>
1340 </listitem>
1341
1342 <listitem>
1343 <para>Select <literal>Add</literal> from the <literal>Image
1344 Library</literal> tab to add a new image file.</para>
1345 </listitem>
1346
1347 <listitem>
1348 <para>Click on <literal>Choose File</literal> to provide the path
1349 to the image file (must be of type
1350 <literal>rootfs.ostree.tar.bz2</literal>). Select the target
1351 hardware platform corresponding to the image being uploaded
1352 (xeon-d or atom-c3000).</para>
1353 </listitem>
1354
1355 <listitem>
1356 <para>Click <literal>Send</literal> to upload the image to the
1357 image repository.</para>
1358 </listitem>
1359 </orderedlist>
1360
1361 <para><emphasis role="bold">Delete an image from the image
1362 repository</emphasis></para>
1363
1364 <orderedlist>
1365 <listitem>
1366 <para>Select <literal>Devices</literal> -&gt;
1367 <literal>Upgrade</literal>.</para>
1368 </listitem>
1369
1370 <listitem>
1371 <para>Select the image you want to delete from the <literal>Image
1372 Library</literal> tab and then click
1373 <literal>Delete</literal>.</para>
1374 </listitem>
1375 </orderedlist>
1376 </section>
1377
1378 <section id="multi_device_install">
1379 <title>Upgrade Operations</title>
1380
1381 <para>The Upgrade Operations tab allows a user to manage device
1382 upgrades in the system. It allows the user to see all the upgrades
1383 that are currently in progress, as well as listing the completed ones.
1384 If an upgrade succeeds or fails, then a row will be added to the
1385 completed upgrades table. If one fails, the failure message will be
1386 visible here.</para>
1387
1388 <note>
1389 <para>The list of completed upgrade tasks resides in memory and will
1390 not persist across reboots of the server.</para>
1391 </note>
1392
1393 <para><emphasis role="bold">How to Install/Upgrade immediately or
1394 schedule for later</emphasis></para>
1395
1396 <orderedlist>
1397 <listitem>
1398 <para>Select <literal>Devices</literal> -&gt;
1399 <literal>Upgrade</literal>.</para>
1400 </listitem>
1401
1402 <listitem>
1403 <para>Select <literal>Upgrade Devices</literal> from the
1404 <literal>Upgrade Operations</literal> tab. This will launch a
1405 <literal>Multi Device Install Image</literal> screen that will
1406 allow the user to install and upgrade more than one device at a
1407 time or upgrade later.</para>
1408
1409 <para>The configurable parameters are:</para>
1410
1411 <itemizedlist>
1412 <listitem>
1413 <para><literal>Scheduling</literal>. Click this checkbox if
1414 the upgrade will be done later. Schedule the day, hour and
1415 minute for when to run the upgrade.</para>
1416
1417 <note>
1418 <para>The hour represents the local uCPE Manager server
1419 hour.</para>
1420 </note>
1421 </listitem>
1422
1423 <listitem>
1424 <para><literal>Description</literal>. An optional description
1425 of the operation. It is recommended to add a description so
1426 that different upgrades happening simultaneously can be
1427 distinguished.</para>
1428 </listitem>
1429
1430 <listitem>
1431 <para><literal>Image File</literal>. Click on <literal>Choose
1432 Image File</literal> to select the image file.</para>
1433 </listitem>
1434
1435 <listitem>
1436 <para><literal>Devices</literal>. The list of available
1437 devices is populated when an image file is chosen. The
1438 device(s) chooser is then populated with the list of devices
1439 that can accept that file. Press the <literal>&gt;</literal>
1440 button to move the devices to the right side of the chooser,
1441 which is the list of devices that will be upgraded.</para>
1442 </listitem>
1443
1444 <listitem>
1445 <para><literal>Upgrade Operation</literal>. Available options
1446 are:</para>
1447
1448 <itemizedlist>
1449 <listitem>
1450 <para><literal>Install and Activate</literal>. This will
1451 do an image installation as well as an upgrade.</para>
1452 </listitem>
1453
1454 <listitem>
1455 <para><literal>Install Only</literal>. This will do an
1456 image installation only. The image is copied to the
1457 device, and an upgrade will be done later either at a
1458 scheduled time or when the option <literal>Activate
1459 Only</literal> is selected.</para>
1460 </listitem>
1461
1462 <listitem>
1463 <para><literal>Activate Only</literal>. This will activate
1464 an already installed image on the device.</para>
1465 </listitem>
1466 </itemizedlist>
1467 </listitem>
1468 </itemizedlist>
1469 </listitem>
1470 </orderedlist>
1471
1472 <note>
1473 <para>When the device activates the upgrade, it will be rebooted
1474 automatically.</para>
1475 </note>
1476 </section>
1477
1478 <section id="check_releases">
1479 <title>Releases installed on a Device</title>
1480
1481 <para>The installed releases on a device can be viewed by selecting
1482 the device first, then from the top toolbar selecting
1483 <literal>Configuration</literal> -&gt; <literal>Upgrade</literal>. The
1484 installed releases on the device, the release status, release state,
1485 commit-id and release version will be listed in a table.</para>
1486 </section>
1487
1488 <section id="check_device_status">
1489 <title>Device Status</title>
1490
1491 <para>The status of the installation and upgrade can be viewed in the
1492 <literal>Upgrade Operations</literal> tab. Ongoing or scheduled
1493 upgrade operations can be viewed or cancelled.</para>
1494
1495 <para><emphasis role="bold">To view the status of an installation or
1496 upgrade operations</emphasis></para>
1497
1498 <orderedlist>
1499 <listitem>
1500 <para>Select <literal>Devices</literal> -&gt;
1501 <literal>Upgrade</literal>.</para>
1502 </listitem>
1503
1504 <listitem>
1505 <para>Select <literal>Upgrade Operations</literal>. The ongoing
1506 operations are listed at the top and a history of failed or
1507 successful operations are listed at the bottom.</para>
1508 </listitem>
1509
1510 <listitem>
1511 <para>Select an <emphasis>Active</emphasis> or <emphasis>Completed
1512 Upgrade Operation</emphasis> and click the <literal>Device
1513 Status</literal> button to see detailed information regarding the
1514 upgrade operation, including the devices involved and information
1515 per device.</para>
1516 </listitem>
1517 </orderedlist>
1518
1519 <para><emphasis role="bold">To cancel an upgrade
1520 operation</emphasis></para>
1521
1522 <orderedlist>
1523 <listitem>
1524 <para>Select <literal>Devices</literal> -&gt; <literal>Upgrade
1525 </literal> -&gt; <literal> Upgrade Operations</literal>.</para>
1526 </listitem>
1527
1528 <listitem>
1529 <para>Select an operation from the list and press <literal>Cancel
1530 Upgrade</literal> and <literal>Confirm</literal>. The operation
1531 will then be deleted from the list.</para>
1532 </listitem>
1533 </orderedlist>
1534 </section>
1535
1536 <section id="device_upgrade_config">
1537 <title>Configuration</title>
1538
1539 <note>
1540 <para>The default values present in the configuration of each device
1541 are recommended for use. Modifying them is for an Advanced User
1542 only.</para>
1543 </note>
1544
1545 <para><emphasis role="bold">How to Configure the uCPE device Upgrade
1546 </emphasis></para>
1547
1548 <orderedlist>
1549 <listitem>
1550 <para>Select <literal>Devices</literal> -&gt;
1551 <literal>Upgrade</literal>.</para>
1552 </listitem>
1553
1554 <listitem>
1555 <para>Select <literal>Configuration</literal>.</para>
1556 </listitem>
1557
1558 <listitem>
1559 <para>The configurable parameters are:</para>
1560
1561 <itemizedlist>
1562 <listitem>
1563 <para><literal>deviceImageDir</literal>. This is the disk
1564 location of the device image repository. If an absolute path
1565 name such as <literal>/usr/local/deviceimage</literal> is
1566 given, then the absolute path name is used. If no absolute
1567 pathname is given it is considered to be relative to the
1568 installation directory.</para>
1569 </listitem>
1570
1571 <listitem>
1572 <para><literal>maxThreads</literal>. This number dictates how
1573 many upgrades the system can manage at one time, either
1574 individually launched or launched from the multi-device
1575 screens. This value defaults to 20, which means that 20
1576 devices may be updated at one time.</para>
1577 </listitem>
1578
1579 <listitem>
1580 <para><literal>KeepAlive</literal>. This number represents the
1581 number of seconds that a thread will be kept alive before it
1582 is collected. If multiple installations are occurring, this
1583 will keep the thread alive for X seconds before it is
1584 released. If not released, it can be used by the internal
1585 scheduling system as soon as it has completed an
1586 upgrade.</para>
1587 </listitem>
1588 </itemizedlist>
1589 </listitem>
1590 </orderedlist>
1591 </section>
1592
1593 <section id="related_func_devup">
1594 <title>Related Functionality for a Device Upgrade</title>
1595
1596 <para>Each device can receive image files and use them to upgrade.
1597 This can be done by selecting the device in the
1598 <literal>System</literal> view and clicking the
1599 <literal>Upgrade</literal> button.</para>
1600
1601 <para>In the new window, an upgrade image can be chosen from the
1602 <literal>Image Files</literal> tab by selecting the image file from
1603 the list and clicking the <literal>Install on Device</literal>
1604 button.</para>
1605
1606 <para>Once an image is installed on the device, the image will be
1607 available on the device and be visible in the
1608 <literal>Releases</literal> tab. It can then be selected from the list
1609 and the upgrade started by clicking the <literal>Upgrade</literal>
1610 button.</para>
1611 </section>
1612 </section>
1613 </section>
1614
1615 <section id="vnf_management">
1616 <title>VNF Management</title>
1617
1618 <para>The Enea uCPE Manager is responsible for onboarding, configuring
1619 (e.g. CloudInit) and ensuring life cycle management of VNFs that are
1620 instantiated and run on the various uCPE devices.</para>
1621
1622 <section id="onboarding_a_vnf">
1623 <title>Onboarding a VNF</title>
1624
1625 <para>The onboarding of a VNF means adding it to the Enea uCPE Manager
1626 VNF Catalog and preparing it for instantiation (deployment on connected
1627 uCPE devices). This is accomplished using the Enea uCPE Manager
1628 Onboarding graphical user interface.</para>
1629
1630 <para>Typically, the Getting Started Guide of a VNF contains all
1631 necessary information needed to onboard a VNF.</para>
1632
1633 <section id="retrieve_art">
1634 <title>Retrieving Artifacts</title>
1635
1636 <para>The user must first retrieve the necessary artifacts from the
1637 VNF vendor:</para>
1638
1639 <orderedlist>
1640 <listitem>
1641 <para>Download the VNF from the commercial vendor.</para>
1642 </listitem>
1643
1644 <listitem>
1645 <para>Procure any VNF-specific files from the VNF vendor, e.g.
1646 license file.</para>
1647
1648 <note>
1649 <para>There are no standard ways of managing VNF licenses,
1650 therefore no general guidelines can be provided. One example of
1651 license handling that can be employed in the uCPE Manager is the
1652 adding of a license during the Cloud-Init setup.</para>
1653 </note>
1654 </listitem>
1655
1656 <listitem>
1657 <para>Optionally, get access to the VNF specific VNF Manager for
1658 day 1 and 2 configuration (in cloud or for local
1659 deployment).</para>
1660 </listitem>
1661
1662 <listitem>
1663 <para>Procure the Getting Started Guide from the VNF vendor,
1664 preferably for KVM deployment for VNF specific configuration
1665 information.</para>
1666 </listitem>
1667 </orderedlist>
1668 </section>
1669
1670 <section id="onboard_prep">
1671 <title>Preparation</title>
1672
1673 <para>Once all needed downloadables, documentation and more have been
1674 attained, preparation for onboarding must be completed:</para>
1675
1676 <orderedlist>
1677 <listitem>
1678 <para>Determine the use-case and performance requirements of the
1679 VNF you wish to deploy:</para>
1680
1681 <itemizedlist spacing="compact">
1682 <listitem>
1683 <para>This decides what resources the VNF is configured for,
1684 along with networking and day zero configurations.</para>
1685
1686 <note>
1687 <para>Generally, the Getting Started Guide for the VNF
1688 provides guidelines for resource allocation, but since
1689 performance is dependent on hardware capacity, the right
1690 resource allocation for deployment is determined through
1691 benchmarking.</para>
1692 </note>
1693 </listitem>
1694
1695 <listitem>
1696 <para>Determine the amount of hardware resources needed for
1697 the VNF (RAM, number of CPUs and storage size).</para>
1698 </listitem>
1699
1700 <listitem>
1701 <para>Determine how many Virtual Network Interfaces the VNF
1702 will use.</para>
1703 </listitem>
1704 </itemizedlist>
1705 </listitem>
1706
1707 <listitem>
1708 <para>Determine the Day-0 configuration method from the VNF
1709 Getting Started guidelines.</para>
1710
1711 <note>
1712 <para>For many VNFs, day zero configuration can be skipped in
1713 early onboarding efforts when automation is not of
1714 importance.</para>
1715 </note>
1716 </listitem>
1717
1718 <listitem>
1719 <para>Determine any requirements needed by the Cloud-Init file
1720 structure and the content needed when this structure is
1721 used.</para>
1722 </listitem>
1723 </orderedlist>
1724 </section>
1725
1726 <section id="onboard_in_ucpemg">
1727 <title>Onboarding into the uCPE Manager</title>
1728
1729 <para><emphasis role="bold">How to onboard a VNF into the uCPE Manager
1730 </emphasis></para>
1731
1732 <orderedlist>
1733 <listitem>
1734 <para>Select from the top toolbar <literal>VNF</literal> -&gt;
1735 <literal>Descriptors</literal></para>
1736 </listitem>
1737
1738 <listitem>
1739 <para>Click the <literal>On-board</literal> button.</para>
1740 </listitem>
1741
1742 <listitem>
1743 <para>When prompted by the UI, make sure the <literal>VM
1744 Image</literal> radio button at the top of the onboarding screen
1745 is selected, it will trigger a popup menu window.</para>
1746 </listitem>
1747 </orderedlist>
1748
1749 <para>This window contains data fields where both necessary and
1750 optional information about the VNF can be supplied. After doing so,
1751 press the Onboard button, the uCPE Manager will create the VNF
1752 descriptor and add it to its VNF Catalog.</para>
1753
1754 <figure>
1755 <title>Onboard a VNF</title>
1756
1757 <mediaobject>
1758 <imageobject>
1759 <imagedata align="center" contentwidth="600"
1760 fileref="images/onboard_a_vnf_image.png" />
1761 </imageobject>
1762 </mediaobject>
1763 </figure>
1764
1765 <para><emphasis role="bold">Main fields</emphasis></para>
1766
1767 <itemizedlist>
1768 <listitem>
1769 <para><emphasis role="bold">VM Image File</emphasis>. This is the
1770 Virtual Machine image file for the VNF. Typically, it is a QCOW
1771 image. Press <literal>Choose File</literal> and select the image
1772 you wish to upload.</para>
1773 </listitem>
1774
1775 <listitem>
1776 <para><emphasis role="bold">Image Format</emphasis>. Select the
1777 format which matches the image file format.</para>
1778 </listitem>
1779
1780 <listitem>
1781 <para><emphasis role="bold">VNF Type Name</emphasis>. This is the
1782 name that will be used to identify this VNF. It will be shown in
1783 the VNFs list.</para>
1784 </listitem>
1785
1786 <listitem>
1787 <para><emphasis role="bold">Description</emphasis>. This field
1788 contains any description provided and is only displayed in the GUI
1789 tables in the uCPE Manager.</para>
1790 </listitem>
1791
1792 <listitem>
1793 <para><emphasis role="bold">Version</emphasis>. This is the
1794 version of the current VNF that you are hosting. It's used to
1795 distinguish this VNF from other versions of the same type.</para>
1796 </listitem>
1797
1798 <listitem>
1799 <para><emphasis role="bold">Memory in MB</emphasis>. This is the
1800 amount of memory (in megabytes) that will be provided to this type
1801 of VNF when it is instantiated. To determine the value for this
1802 field, consult the VNF vendor.</para>
1803 </listitem>
1804
1805 <listitem>
1806 <para><emphasis role="bold">Num of CPUs</emphasis>. The number of
1807 CPUs that will be dedicated to an instance of this VNF when
1808 created. To determine the value for this field, consult the VNF
1809 vendor.</para>
1810 </listitem>
1811
1812 <listitem>
1813 <para><emphasis role="bold">Storage in GB</emphasis>. How much
1814 disk space to provide an instance of this VNF. To determine the
1815 value for this field, consult the VNF vendor.</para>
1816 </listitem>
1817 </itemizedlist>
1818
1819 <para><emphasis role="bold">Interfaces Tab</emphasis></para>
1820
1821 <para>Click on the <literal>Interfaces</literal> tab to show the
1822 Interfaces table.</para>
1823
1824 <para>This table will contain the interfaces required by this VNF to
1825 be configured, when creating an instance. Consult the VNF vendor to
1826 determine which and how many are required. Each interface requires a
1827 name, and optionally a description, used only by the uCPE
1828 Manager.</para>
1829
1830 <note>
1831 <para>CAUTION: The user MUST conserve the same order for the virtual
1832 interfaces during both onboarding and instantiation phases.</para>
1833 </note>
1834
1835 <para><emphasis role="bold">Cloud Init Tab</emphasis></para>
1836
1837 <para>Click the <literal>Clout Init</literal> tab to provide the
1838 Clout-Init configuration. There are three fields that need to be
1839 populated:</para>
1840
1841 <orderedlist>
1842 <listitem>
1843 <para><emphasis role="bold">Cloud-Init
1844 Datasource</emphasis></para>
1845
1846 <para>To onboard a VNF you must specify the <literal>Cloud-Init
1847 Datasource</literal> that the VNF uses. This information is
1848 procured from the VNF Vendor. Choose one of the following methods
1849 to specify the datasource:</para>
1850
1851 <itemizedlist spacing="compact">
1852 <listitem>
1853 <para><emphasis role="bold">None</emphasis>. If there is no
1854 datasource.</para>
1855 </listitem>
1856
1857 <listitem>
1858 <para><emphasis role="bold">ConfigDrive</emphasis>. This
1859 method allows you to provide any number of content-data files
1860 containing Cloud-Init data.</para>
1861 </listitem>
1862
1863 <listitem>
1864 <para><emphasis role="bold">NoCloud</emphasis>. This is a
1865 simpler method that uses only one cloud init file
1866 (User-Data).</para>
1867 </listitem>
1868
1869 <listitem>
1870 <para><emphasis role="bold">ISO</emphasis>. Pre-cooked
1871 cloud-init image. This image must be created by the user
1872 according to VNF requirements.</para>
1873 </listitem>
1874 </itemizedlist>
1875 </listitem>
1876
1877 <listitem>
1878 <para><emphasis role="bold">Cloud-Init Disk Type</emphasis></para>
1879
1880 <para>The <literal>Cloud-Init Disk Type</literal> field must be
1881 set to either <literal>Disk</literal>, or
1882 <literal>CD-ROM</literal>, depending on what the VNF requires. You
1883 can get this information from the VNF Vendor.</para>
1884 </listitem>
1885
1886 <listitem>
1887 <para><emphasis role="bold">Content Files Table</emphasis></para>
1888
1889 <para>The <literal>Content Files Table </literal>is ONLY used if
1890 you choose <literal>ConfigDrive</literal> as the Cloud-Init
1891 Datasource. For each content file added, you must provide a
1892 <literal>Path</literal>. When a user uses the uCPE Manager to
1893 create an instance for multiple VNFs, they will be prompted to
1894 provide a data file for each entry in this table. Each type of VNF
1895 will require different cloud-init files, e.g.: a license file. The
1896 data files will be added to the cloud-init image that the user
1897 provides at the instantiation of the VNF. If the cloud-init image
1898 is not provided, no Cloud-Init Data Source will be created for
1899 that VNF and there will be no warning.</para>
1900 </listitem>
1901 </orderedlist>
1902
1903 <para>Consult with the VNF vendor to determine what is required for
1904 the VNF you are onboarding.</para>
1905
1906 <para><emphasis role="bold">Properties Tab</emphasis></para>
1907
1908 <para>In this table, you can enter values for properties that will be
1909 used during instantiation of the VNF. The values will augment the
1910 default values in the <filename>Domain.XML</filename> file used by
1911 <literal>libvirt/virsh</literal> (running in NFV Access) when creating
1912 an instance of the VNF. Consult with the VNF Vendor or ENEA support
1913 for values needed by specific VNFs.</para>
1914
1915 <para><emphasis role="bold">Property Values</emphasis></para>
1916
1917 <itemizedlist>
1918 <listitem>
1919 <para><literal>numHugePages</literal> defines the number of huge
1920 memory pages the VNF uses (for DPDK).</para>
1921 </listitem>
1922
1923 <listitem>
1924 <para><literal>vnfMgmtIpAddress</literal>: the IP address of the
1925 VNF's management interface, connected to a
1926 <literal>vnfMgmt</literal> bridge (e.g. 10.0.0.2).</para>
1927 </listitem>
1928
1929 <listitem>
1930 <para><literal>internalMgmtPort</literal>: the VNF's TCP/UDP port
1931 used for management (e.g. 443).</para>
1932 </listitem>
1933
1934 <listitem>
1935 <para><literal>externalMgmtPort</literal>: the Management port
1936 used for external access (e.g. 60001).</para>
1937 </listitem>
1938 </itemizedlist>
1939
1940 <note>
1941 <para>The last three properties are useful in conjuction with the
1942 <literal>vnfMgmt</literal> bridge type. They allow the user to map
1943 the internal VNF management port to an external port, useful for VNF
1944 configuration from WAN.</para>
1945
1946 <para>In the previous example, the internal TCP port 443 (HTTPS) was
1947 mapped to the external port 60001, which allows the user to access
1948 the VNF management port from a web browser e.g.
1949 <literal>https://&lt;WAN_IP&gt;:60001</literal>.</para>
1950 </note>
1951 </section>
1952 </section>
1953
1954 <section id="instantiating_a_vnf">
1955 <title>Instantiating a VNF</title>
1956
1957 <para>When a VNF is onboarded and available in the VNF catalog, it can
1958 be instantiated on connected uCPE devices. The configurations provided
1959 when the VNF is onboarded, serve as a template for instantiation. Before
1960 instantiating any VNF, please make sure the available storage space on
1961 the uCPE device is big enough to accommodate the VNF you need to
1962 instantiate.</para>
1963
1964 <para>Follow the instructions below to instantiate a VNF:</para>
1965
1966 <orderedlist>
1967 <listitem>
1968 <para>Select from the top toolbar <literal>VNF</literal> -&gt;
1969 <literal>Instances</literal></para>
1970 </listitem>
1971
1972 <listitem>
1973 <para>Click the <literal>Add</literal> button.</para>
1974 </listitem>
1975
1976 <listitem>
1977 <para>Fill out the following mandatory fields:</para>
1978
1979 <itemizedlist spacing="compact">
1980 <listitem>
1981 <para>Name: a descriptive name.</para>
1982 </listitem>
1983
1984 <listitem>
1985 <para>VNF Type: a list of onboarded VNFs.</para>
1986 </listitem>
1987
1988 <listitem>
1989 <para>uCPE Device: the uCPE device to instantiate the VNF
1990 on.</para>
1991 </listitem>
1992
1993 <listitem>
1994 <para>Networking Configuration:</para>
1995
1996 <itemizedlist spacing="compact">
1997 <listitem>
1998 <para>Connect each configured NIC with a bridge, SR-IOV or
1999 PCI Passthrough.</para>
2000 </listitem>
2001
2002 <listitem>
2003 <para>Set up each NIC with a driver method.</para>
2004 </listitem>
2005 </itemizedlist>
2006
2007 <note>
2008 <para>All configured NICs must be set up before instantiating
2009 a VNF. Failure to do so will end in a failed
2010 instantiation.</para>
2011 </note>
2012 </listitem>
2013 </itemizedlist>
2014 </listitem>
2015
2016 <listitem>
2017 <para>Add VNF-specific configuration data by uploading a Cloud-Init
2018 file (when the Cloud-Init is used).</para>
2019 </listitem>
2020
2021 <listitem>
2022 <para>Add any VNF-specific files (e.g license files).</para>
2023 </listitem>
2024
2025 <listitem>
2026 <para>Hit the <literal>Create</literal> button to deploy the VNF and
2027 run it on the specified uCPE device.</para>
2028 </listitem>
2029 </orderedlist>
2030
2031 <para>Selecting the<literal> VNF -&gt; Events</literal> menu will show
2032 that the VNF was created and a connection was established.</para>
2033 </section>
2034
2035 <section id="enter_console">
2036 <title>Accessing the VNF console</title>
2037
2038 <para>Once the VNF is deployed, the VNF console can be entered using SSH
2039 and virsh commands. The VNF Console is a typical starting point for
2040 determining a successful deployment and configuring a VNF beyond Day
2041 Zero.</para>
2042
2043 <orderedlist>
2044 <listitem>
2045 <para>SSH to the uCPE device from the Enea uCPE Manager
2046 (<literal>Device-&gt;SSH</literal>) using:</para>
2047
2048 <itemizedlist>
2049 <listitem>
2050 <para>For normal connections: the <literal>Username</literal>
2051 (default: root), the <literal>Password</literal> (default: no
2052 password), the <literal>Port</literal> (default: 22) and the
2053 <literal>Reverse ssh</literal> checkbox: unchecked.</para>
2054 </listitem>
2055
2056 <listitem>
2057 <para>For reverse ssh connections: the
2058 <literal>Username</literal> (default: root) and the
2059 <literal>Reverse ssh</literal> checkbox checked. The port will
2060 be automatically choosen by the uCPE Manager in the range
2061 defined in the <literal>System -&gt; Configuration -&gt; Reverse
2062 SSH</literal> configuration panel. By default, the start port
2063 will be <literal>7000</literal> and the maximum number of ports
2064 allocated to all devices is 10. Only one port per device is
2065 allowed.</para>
2066
2067 <para>A SSH Tunnel between the uCPE Manager and the device will be created:</para>
2068 <programlisting>ssh -f -N -T -R &lt; Port &gt; :localhost:22 &lt;uCPE Mgr user&gt;@&lt;uCPE MgrIP&gt;</programlisting>
2069 <para>The device must be connected to the uCPE Manager for the tunnel to be created.
2070 On connection, a normal ssh connection will be made:</para>
2071 <programlisting>ssh -p &lt;Port&gt; &lt;Username&gt;@localhost</programlisting>
2072
2073
2074 </listitem>
2075 </itemizedlist>
2076 </listitem>
2077
2078 <listitem>
2079 <para>In SSH:</para>
2080
2081 <orderedlist spacing="compact">
2082 <listitem>
2083 <para>Use the <command>virsh list</command> command to list all
2084 running VNFs and to determine the VNF's instance number.</para>
2085 </listitem>
2086
2087 <listitem>
2088 <para>Use the <command>virsh console &lt;instance
2089 number&gt;</command> command to enter the VNF-specific
2090 console.</para>
2091 </listitem>
2092 </orderedlist>
2093 </listitem>
2094 </orderedlist>
2095 </section>
2096 </section>
2097</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/archive_list.png b/doc/book-enea-nfv-access-getting-started/doc/images/archive_list.png
new file mode 100755
index 0000000..302f32d
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/archive_list.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/collect_debug_logs.png b/doc/book-enea-nfv-access-getting-started/doc/images/collect_debug_logs.png
new file mode 100755
index 0000000..6582737
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/collect_debug_logs.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/debug_settings.png b/doc/book-enea-nfv-access-getting-started/doc/images/debug_settings.png
new file mode 100755
index 0000000..2c97b2c
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/debug_settings.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/dev_file_mg.png b/doc/book-enea-nfv-access-getting-started/doc/images/dev_file_mg.png
new file mode 100755
index 0000000..a4a4f5c
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/dev_file_mg.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/download_files.png b/doc/book-enea-nfv-access-getting-started/doc/images/download_files.png
new file mode 100755
index 0000000..cb686e4
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/download_files.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/fault_events.png b/doc/book-enea-nfv-access-getting-started/doc/images/fault_events.png
new file mode 100755
index 0000000..aeec955
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/fault_events.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/prep_deploy.png b/doc/book-enea-nfv-access-getting-started/doc/images/prep_deploy.png
new file mode 100755
index 0000000..e93e7f1
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/prep_deploy.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/prep_execution.png b/doc/book-enea-nfv-access-getting-started/doc/images/prep_execution.png
new file mode 100755
index 0000000..b783076
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/prep_execution.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/images/vnf_space.png b/doc/book-enea-nfv-access-getting-started/doc/images/vnf_space.png
index d4f8fde..1a5ddab 100755
--- a/doc/book-enea-nfv-access-getting-started/doc/images/vnf_space.png
+++ b/doc/book-enea-nfv-access-getting-started/doc/images/vnf_space.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml b/doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml
new file mode 100644
index 0000000..19a3397
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml
@@ -0,0 +1,996 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="installation_guide">
3 <title>Setting up and Installing the NFV Access 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 CentOS 7 server</para>
18
19 <para>Minimal Requirement: 4 Cores, 16 GB RAM and 300 GB single disk
20 storage. Make sure the CentOS 7 server is updated to the latest
21 revision before installing Enea NFV Access.</para>
22
23 <para>The purpose of the CentOS 7 server is to host the uCPE Manager.
24 Network access between the CentOS 7 server and the uCPE devices is
25 required. The uCPE Manager and the uCPE devices will be connected on
26 separate subnets to avoid inconsistencies.</para>
27 </listitem>
28
29 <listitem>
30 <para>A laptop.</para>
31
32 <para>The laptop is used for 2 scenarios:</para>
33
34 <itemizedlist>
35 <listitem>
36 <para>Installing the NFV Access Run Time Platform on uCPE
37 Devices.</para>
38 </listitem>
39
40 <listitem>
41 <para>Connecting to the Web UI of the uCPE Manager for management
42 and configuration. Network access between the CentOS 7 server and
43 the laptop is required. Please see the <xi:include
44 href="../../s_docbuild/olinkdb/pardoc-common.xml"
45 xmlns:xi="http://www.w3.org/2001/XInclude"
46 xpointer="element(book_enea_nfv_access_release_info/1)" /> manual
47 available with your release, for recommended browsers.</para>
48 </listitem>
49 </itemizedlist>
50 </listitem>
51
52 <listitem>
53 <para>One or more uCPE devices.</para>
54
55 <para>White Box devices where the Enea NFV Access Runtime Platform
56 will be installed, containing a minimum of 2 cores and 4 GB RAM and at
57 least two ethernet ports that will be configured as WAN and LAN during
58 deployment.</para>
59
60 <para>When hosting an entire solution including one or several network
61 services, the hardware must also have the resources to host one or
62 more VNFs. During a typical evaluation, a dual VNF service on the Enea
63 NFV Access Run Time Platform needs a CPU with 4-8 cores and at least 8
64 GB RAM. The supported Intel CPUs of Enea NFV Access are documented in
65 the <xi:include href="../../s_docbuild/olinkdb/pardoc-common.xml"
66 xmlns:xi="http://www.w3.org/2001/XInclude"
67 xpointer="element(book_enea_nfv_access_release_info/1)" />
68 manual.</para>
69
70 <para>Enea NFV Access needs EFI support in BIOS to boot. When
71 configuring the uCPE device BIOS a serial connection is
72 required.</para>
73 </listitem>
74
75 <listitem>
76 <para>A 16 GB USB stick used for the uCPE Device Installation.</para>
77 </listitem>
78 </itemizedlist>
79 </section>
80
81 <section id="sw_config">
82 <title>Software Configuration</title>
83
84 <para>The CentOS 7 machine requires a specific configuration for the setup
85 to work.</para>
86
87 <section id="firewall_config">
88 <title>Firewall Configuration</title>
89
90 <para>Any firewall running on the CentOS 7 server may block the
91 management protocols required to communicate between the uCPE device and
92 the uCPE Manager as well as between the uCPE Manager and its northbound
93 clients. Quick handling of a blocking firewall would be to disable it,
94 typical for a lab environment, through:</para>
95
96 <programlisting>sudo service firewalld stop</programlisting>
97
98 <para>For an advanced firewall configuration, the following ports need
99 to be opened:</para>
100
101 <table>
102 <title>Ports to be Activated</title>
103
104 <tgroup cols="3">
105 <colspec align="left" />
106
107 <tbody>
108 <row>
109 <entry>80</entry>
110
111 <entry>TCP</entry>
112
113 <entry>Required for WEB UI Access.</entry>
114 </row>
115
116 <row>
117 <entry>443</entry>
118
119 <entry>TCP</entry>
120
121 <entry>Required for WEB UI Access and Device
122 Connectivity.</entry>
123 </row>
124
125 <row>
126 <entry>54327</entry>
127
128 <entry>UDP</entry>
129
130 <entry>TBD.<remark>This needs to be updated</remark></entry>
131 </row>
132
133 <row>
134 <entry>5701:5708</entry>
135
136 <entry>TCP</entry>
137
138 <entry>Required for the uCPE Manager Redundancy
139 Protocol.</entry>
140 </row>
141
142 <row>
143 <entry>4334</entry>
144
145 <entry>TCP</entry>
146
147 <entry>Required for Call Home.</entry>
148 </row>
149
150 <row>
151 <entry>2021:2040</entry>
152
153 <entry>TCP</entry>
154
155 <entry>Required for Call Home.</entry>
156 </row>
157
158 <row>
159 <entry>7000:7010</entry>
160
161 <entry>TCP</entry>
162
163 <entry>Required for Reverse SSH.</entry>
164 </row>
165 </tbody>
166 </tgroup>
167 </table>
168
169 <para>Use the following command sequence to enable the required ports
170 for deployment of the uCPE Manager:</para>
171
172 <programlisting>sudo firewall-cmd --permanent --add-service=80/tcp
173sudo firewall-cmd --permanent --add-service=443/tcp
174sudo firewall-cmd --permanent --add-service=54327/udp
175sudo firewall-cmd -permanent -add-service=5701-5708/tcp
176sudo firewall-cmd --permanent --add-service=4334/tcp
177sudo firewall-cmd -permanent -add-service=2021-2040/tcp
178sudo firewall-cmd -reload</programlisting>
179 </section>
180
181 <section id="openjdk_postgresql_config">
182 <title>Configuring OpenJDK and PostgreSQL</title>
183
184 <para>The uCPE Manager requires a specific Java version (OpenJDK 11) and
185 a PostgreSQL version to operate correctly.</para>
186
187 <para><emphasis role="bold">Installing OpenJDK</emphasis></para>
188
189 <orderedlist>
190 <listitem>
191 <para>Install OpenJDK 11 using the root account:</para>
192
193 <programlisting>yum install java-11-openjdk-devel</programlisting>
194 </listitem>
195
196 <listitem>
197 <para>Verify the installation:</para>
198
199 <programlisting>java -version
200openjdk version "11.0.3" 2019-04-16 LTS
201OpenJDK Runtime Environment 18.9 (build 11.0.3+7-LTS)
202OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing) </programlisting>
203
204 <note>
205 <para>If there are multiple java versions installed, switch
206 between them using the following command:</para>
207
208 <programlisting>alternatives --config java</programlisting>
209
210 <para>Optionally, the user can switch between the
211 <literal>javac</literal> versions using:</para>
212
213 <programlisting>alternatives --config javac</programlisting>
214 </note>
215 </listitem>
216
217 <listitem>
218 <para>The following system variables need to point to the OpenJDK 11
219 installation:</para>
220
221 <programlisting>export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which javac)))))
222export PATH=$PATH:$JAVA_HOME/bin
223export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar</programlisting>
224
225 <para>Store updates of the variables <literal>PATH</literal>,
226 <literal>JAVA_HOME</literal>, and <literal>CLASSPATH</literal> in
227 the <filename>.bash_profile</filename> file of the root user.</para>
228
229 <note>
230 <para>In order to make these system variables persistent, the
231 commands given above should be added to a script in the
232 <literal>/etc/profile.d/</literal> folder. <emphasis
233 role="bold">Sudo</emphasis> access is needed for this
234 operation.</para>
235 </note>
236 </listitem>
237 </orderedlist>
238
239 <para>The uCPE Manager requires a specific PostgreeSQL version. This is
240 embedded in the uCPE Manager installation. In order to avoid conflicts,
241 any existing installation needs to be uninstalled.</para>
242
243 <para><emphasis role="bold">Uninstalling PostgreSQL</emphasis></para>
244
245 <orderedlist>
246 <listitem>
247 <para>Open a terminal with administrative rights, i.e. log into a
248 bash shell with root privileges.</para>
249 </listitem>
250
251 <listitem>
252 <para>Execute the following command to check if you have a currently
253 running the PostgreSQL database server:</para>
254
255 <programlisting>ps -ef | grep post</programlisting>
256 </listitem>
257
258 <listitem>
259 <para>Remove the currently installed PostgreSQL server (including
260 the existing postgres user):</para>
261
262 <programlisting>yum remove postgres\*
263rm -f /var/lib/pgsql
264rm -f /etc/postgres-reg.ini
265userdel postgres</programlisting>
266
267 <note>
268 <para>This step is not necessary if the uCPE Manager will be using
269 an external database (like MariaDB).</para>
270 </note>
271 </listitem>
272 </orderedlist>
273
274 <para>If you have multiple spindles, it is recommended to let the
275 application run off one and the database off the other. This will result
276 in optimum performance. It is also recommended that the swap disk be the
277 same as the one used for the application.</para>
278
279 <para>Assuming another spindle is used (<literal>/drive2</literal>) do
280 the following:</para>
281
282 <orderedlist>
283 <listitem>
284 <para>Create a folder which will host the database (e.g.
285 <literal>emsDatabase</literal>).</para>
286 </listitem>
287
288 <listitem>
289 <para>Create a soft-link that will point to this folder:</para>
290
291 <programlisting>ln -s /opt/ems/elementcenter/database /drive2/emsDatabase</programlisting>
292 </listitem>
293
294 <listitem>
295 <para>Follow the installation process as described below.</para>
296 </listitem>
297 </orderedlist>
298 </section>
299 </section>
300
301 <section id="ucpe_config">
302 <title>uCPE Device configuration</title>
303
304 <section id="wan_lan_ports">
305 <title>Determining the WAN and LAN ports</title>
306
307 <para>A typical White box comes with multiple physical network ports,
308 ready to be used. The user must determine the purpose and allocation of
309 each port. The allocation is later aligned with the software
310 configuration within the Enea NFV Access installer.</para>
311
312 <para>A common way is to allocate the left ports to WANs and the right
313 ports to LANs. At least one port must be allocated to WAN and one to
314 LAN.</para>
315 </section>
316
317 <section id="ucpe_identifier">
318 <title>Determining the uCPE Identifier</title>
319
320 <para>Each uCPE device needs a unique identifier. This identifier is
321 used to match the registration in the uCPE Manager and the offline
322 configuration of the uCPE device during ZTP (Zero Touch
323 Provisioning)</para>
324
325 <para>Select a text string to represent the uCPE device, e.g.
326 <literal>uCPE-1</literal> or
327 <literal>fwa-t1012vc_boston_1234</literal>.</para>
328 </section>
329
330 <section id="bios_config">
331 <title>Configuring the BIOS</title>
332
333 <para>The factory configuration of the BIOS may not match the
334 requirements of Enea NFV Access. The BIOS configuration needs to be
335 reviewed and potentially reconfigured to prepare for a successful
336 installation.</para>
337
338 <para>Access the BIOS using a serial cable between the uCPE device and
339 the laptop, to review and configure the BIOS correctly. The White box
340 vendor is expected to provide the right serial cable for the box. A
341 terminal emulator (such as putty) is needed on the laptop.</para>
342
343 <para>Enable the following BIOS features/configurations:</para>
344
345 <itemizedlist>
346 <listitem>
347 <para>EFI</para>
348 </listitem>
349
350 <listitem>
351 <para>Intel Virtualization Technology (VT-x)</para>
352 </listitem>
353
354 <listitem>
355 <para>Intel Virtualization Technology for Directed I/O (VT-d)</para>
356 </listitem>
357
358 <listitem>
359 <para>SR-IOV</para>
360 </listitem>
361 </itemizedlist>
362
363 <para>The boot order may also need to be modified to support
364 installation and execution of the Enea NFV Access Runtime Platform on
365 the uCPE device.</para>
366
367 <para>The following boot order is recommended for a base
368 configuration:</para>
369
370 <orderedlist>
371 <listitem>
372 <para>Boot from USB</para>
373 </listitem>
374
375 <listitem>
376 <para>Boot from Disk</para>
377 </listitem>
378 </orderedlist>
379
380 <para>With the above boot order there is no need for a configuration of
381 the BIOS during installation and deployment.</para>
382 </section>
383 </section>
384
385 <section id="prep_deploy">
386 <title>Preparing the deployment</title>
387
388 <section id="instal_ucpe_mg">
389 <title>Installing the uCPE Manager</title>
390
391 <para>On the CentOS 7 server open a terminal, log into a bash shell with
392 the root account and perform the following:</para>
393
394 <orderedlist>
395 <listitem>
396 <para>Unzip
397 <literal>Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</literal></para>
398
399 <para>The directory in which the archive has been unpacked will be
400 denoted as: <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
401 </listitem>
402
403 <listitem>
404 <para>Enter <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
405 </listitem>
406
407 <listitem>
408 <para>Choose the target installation folder, e.g.
409 <literal>/opt/ems</literal>. Everything will be installed under a
410 folder called <literal>/ucpemanager</literal> within the target
411 installation folder.</para>
412
413 <para>The application files will be installed in
414 <literal>/opt/ems/ucpemanager/application</literal>. The database
415 will be installed in
416 <literal>/opt/ems/ucpemanager/database</literal>.</para>
417 </listitem>
418
419 <listitem>
420 <para>Run the following interactive command:</para>
421
422 <programlisting>./install.sh /opt/ems \
423Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
424
425 <para>Use the default configuration values provided below in the
426 interactive install command. The same configuration values will need
427 to be provided when upgrading or uninstalling the uCPE
428 Manager:</para>
429
430 <itemizedlist>
431 <listitem>
432 <para>Database Configurations:</para>
433
434 <itemizedlist spacing="compact">
435 <listitem>
436 <para>Are you using the embedded PostgreSQL database? [Y/N]:
437 <literal>Y</literal>.</para>
438 </listitem>
439
440 <listitem>
441 <para>Specify the database process password:
442 <literal>postgres</literal>.</para>
443 </listitem>
444
445 <listitem>
446 <para>Specify the database ID (or name):
447 <literal>ucpemanager</literal>.</para>
448 </listitem>
449
450 <listitem>
451 <para>Specify the database server port:
452 <literal>5432</literal>.</para>
453 </listitem>
454
455 <listitem>
456 <para>Specify the database user name:
457 <literal>postgres</literal>.</para>
458 </listitem>
459
460 <listitem>
461 <para>Specify database password:
462 <literal>postgres</literal>.</para>
463 </listitem>
464
465 <listitem>
466 <para>Specify database startup thread pool size:
467 <literal>1</literal>.</para>
468 </listitem>
469 </itemizedlist>
470 </listitem>
471
472 <listitem>
473 <para>Service Configurations:</para>
474
475 <itemizedlist spacing="compact">
476 <listitem>
477 <para>Specify service username:
478 <literal>ucpemanager</literal>.</para>
479 </listitem>
480
481 <listitem>
482 <para>Specify service password:
483 <literal>ucpemanager</literal>.</para>
484 </listitem>
485 </itemizedlist>
486 </listitem>
487
488 <listitem>
489 <para>High Availability Configurations:</para>
490
491 <itemizedlist spacing="compact">
492 <listitem>
493 <para>Specify the IP address of the local interface: The
494 CentOS 7 loopback address: 127.0.0.1.</para>
495 </listitem>
496
497 <listitem>
498 <para>Is this server part of a cluster? [Y/N]:
499 <literal>N</literal>.</para>
500 </listitem>
501 </itemizedlist>
502 </listitem>
503
504 <listitem>
505 <para>Heap Configuration:</para>
506
507 <itemizedlist spacing="compact">
508 <listitem>
509 <para>Please enter the new Maximum Heap Size: <literal>4
510 GB</literal>.<remark>Is this value accurate?</remark></para>
511 </listitem>
512 </itemizedlist>
513 </listitem>
514 </itemizedlist>
515
516 <para>This command will:</para>
517
518 <itemizedlist spacing="compact">
519 <listitem>
520 <para>Extract the application files from the compressed
521 installation kit.</para>
522 </listitem>
523
524 <listitem>
525 <para>Install the bundled database.</para>
526 </listitem>
527
528 <listitem>
529 <para>Install the uCPE Manager as a service with the name
530 <literal>ucpemanager</literal>.</para>
531 </listitem>
532
533 <listitem>
534 <para>Start the <literal>ucpemanager</literal> service</para>
535 </listitem>
536 </itemizedlist>
537 </listitem>
538
539 <listitem>
540 <para>Open the IP Address of the CentOS 7 in a web browser on the
541 laptop and log in with the username and password:
542 <literal>admin</literal>/<literal>admin</literal>.</para>
543 </listitem>
544 </orderedlist>
545
546 <note>
547 <para>The IPv4 address of the CentOS 7 server, connected to the same
548 network as the uCPE Devices, will be used as a configuration parameter
549 both when setting up the uCPE devices and when accessing the uCPE
550 Manager GUI.</para>
551 </note>
552
553 <para>The uCPE Manager can be restored if a back-up file has been
554 previously created. A backup file can be created by accessing from the
555 uCPE Manager GUI: <literal>System</literal> -&gt; <literal>System
556 Backup</literal>. The resulting zip archive will be located in the
557 <filename>/opt/ems/ucpemanager/application/backup</filename> folder and
558 will be named <literal>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</literal>
559 (e.g System-Backup_Feb19_2013_2257_42.zip). Save the archive to another
560 location outside the uCPE Manager installation folder for future
561 use.</para>
562
563 <note>
564 <para>The System Back-up file obtained from the uCPE Manager GUI
565 (<filename>SystemBackup_MMMDD_YYYY_HHMM_SS.zip</filename>) must be
566 used to recover the uCPE Manager during deployment.</para>
567
568 <para>This is different from the uCPE Manager snapshot obtained during
569 a uCPE Manager Upgrade or Uninstall Operation
570 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>).<remark>Why
571 do both options exist, what makes them different from each
572 other?</remark></para>
573 </note>
574
575 <para>To install the uCPE Manager with the restore option provide an
576 additional argument as shown below during installation:</para>
577
578 <programlisting>./install.sh \
579/opt/ems Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz \
580SystemBackup_MMMDD_YYYY_HHMM_SS.zip</programlisting>
581 </section>
582
583 <section id="prep_usb_ena">
584 <title>Preparing the USB stick for installation of the NFV Access Run
585 Time Platform</title>
586
587 <para>To install the Enea NFV Access Run Time Platform, create a
588 bootable USB stick with the image you intend to install. Follow the
589 example below to proceed.</para>
590
591 <note>
592 <para>The .hddimg image is available in the
593 <filename>Enea_NFV_Access_Run_Time_Platform_
594 &lt;processor&gt;_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
595 file you downloaded with your release.</para>
596 </note>
597
598 <para><emphasis role="bold">Create a bootable USB stick
599 image</emphasis></para>
600
601 <orderedlist>
602 <listitem>
603 <para>Copy the <filename>.hddimg</filename> image file provided by
604 Enea, into the CentOS 7 server.</para>
605 </listitem>
606
607 <listitem>
608 <para>Connect the USB stick to the CentOS 7 Server and identify the
609 USB device name given by the system with
610 <literal>lsblk</literal>:</para>
611
612 <programlisting>NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
613sda 8:0 1 28.7G 0 disk
614sdb 8:0 0 111.8G 0 disk
615|-sdb1 8:1 0 111.8G 0 part</programlisting>
616 </listitem>
617
618 <listitem>
619 <para>Copy the <filename>.hddimg</filename> image onto the USB
620 stick, e.g:</para>
621
622 <programlisting>sudo dd if=./enea-nfv-access-&lt;machine&gt;.hddimg \
623of=/dev/sdb bs=4M conv=fsync</programlisting>
624
625 <para>Where
626 <filename>enea-nfv-access-&lt;machine&gt;.hddimg</filename> is the
627 <filename>.hddimg</filename> file and <literal>sdb</literal> is the
628 assigned USB device name.</para>
629 </listitem>
630 </orderedlist>
631 </section>
632
633 <section id="prep_phys_deploy">
634 <title>Preparing physical deployment for installation</title>
635
636 <figure>
637 <title>Preparing for Hardware Installation</title>
638
639 <mediaobject>
640 <imageobject>
641 <imagedata contentwidth="600" fileref="images/prep_deploy.png" />
642 </imageobject>
643 </mediaobject>
644 </figure>
645
646 <para>The following hardware configuration is needed to install uCPE
647 devices:</para>
648
649 <orderedlist>
650 <listitem>
651 <para>Network connection between the CentOS 7 server and the
652 laptop.</para>
653 </listitem>
654
655 <listitem>
656 <para>The uCPE device is powered off.</para>
657 </listitem>
658
659 <listitem>
660 <para>Direct Ethernet cable connection between the uCPE Device LAN
661 and the laptop.</para>
662 </listitem>
663 </orderedlist>
664 </section>
665
666 <section id="install_ena_device">
667 <title>Installing Enea NFV Access - uCPE Device installation</title>
668
669 <para>To initiate the installation of the NFV Access Run Time Platform
670 do the following:</para>
671
672 <orderedlist>
673 <listitem>
674 <para>Plug the USB stick into the uCPE device.</para>
675 </listitem>
676
677 <listitem>
678 <para>Connect a laptop directly into one of the uCPE device ports.
679 This can't be used as a WAN port at a later moment. No other ports
680 should be connected.</para>
681 </listitem>
682
683 <listitem>
684 <para>Power up the uCPE device and boot the USB stick.</para>
685 </listitem>
686
687 <listitem>
688 <para>The Web-installer application will start automatically and can
689 be accessed in a web browser on the laptop at
690 <literal>http://172.16.1.1</literal> (port 80).</para>
691 </listitem>
692
693 <listitem>
694 <para>On the first page of the Web-installer, the user must fill
695 in:</para>
696
697 <itemizedlist>
698 <listitem>
699 <para>The static uCPE Manager IP Address.</para>
700 </listitem>
701
702 <listitem>
703 <para>The unique identifier of the uCPE device (called "uCPE
704 Identifier" in this guide).</para>
705 </listitem>
706
707 <listitem>
708 <para>Customer Tags. They are used for Zero Touch Provisining
709 (ZTP) and can be left empty for a base configuration. What can
710 be entered here (if needed), are the tag(s) specified when
711 creating an offline configuration in the uCPE Manager. A later
712 addition of customer tags can only be done by reinstalling the
713 uCPE devices.</para>
714 </listitem>
715 </itemizedlist>
716 </listitem>
717
718 <listitem>
719 <para>On the second page of the Web-installer, the user must fill
720 in:</para>
721
722 <itemizedlist>
723 <listitem>
724 <para>The Layer 3 configuration of WAN Interface(s).</para>
725 </listitem>
726
727 <listitem>
728 <para>The Static or Dynamic IP.</para>
729 </listitem>
730
731 <listitem>
732 <para>During network configuration, WAN cables are plugged into
733 the uCPE device to identify ports and make them available for
734 configuration. All ports with cable connections will be set as
735 WAN ports and must be configured (DHCP is the default setting).
736 The configured WAN ports cannot be removed after configuration.
737 The user needs to connect the same number of cables as the
738 number of WAN ports that he wishes to configure. The configured
739 WAN cables cannot be removed after being configured.</para>
740
741 <note>
742 <para>No LAN ports should be connected nor configured at this
743 time. The LAN port used to access the Web-installer from the
744 laptop will not be shown and cannot be configured in the Web
745 Installer.</para>
746 </note>
747 </listitem>
748
749 <listitem>
750 <para>The Management Interface. The network interface (IP
751 Address of the uCPE Manager) used by the uCPE Manager to
752 communicate with the uCPE device.</para>
753 </listitem>
754 </itemizedlist>
755 </listitem>
756 </orderedlist>
757
758 <para>When the user has completed the configuration steps in the
759 Web-installer, NFV Access is installed on the hard drive. The largest
760 drive found on the uCPE device will be used for installation.</para>
761 </section>
762
763 <section id="prep_phys_exec">
764 <title>Preparing physical deployment for execution</title>
765
766 <figure>
767 <title>Preparing for Deployment Execution</title>
768
769 <mediaobject>
770 <imageobject>
771 <imagedata contentwidth="600" fileref="images/prep_execution.png" />
772 </imageobject>
773 </mediaobject>
774 </figure>
775
776 <para>The following hardware configuration is needed for service
777 deployment:</para>
778
779 <itemizedlist>
780 <listitem>
781 <para>Network connection between the CentOS 7 server and the
782 laptop.</para>
783 </listitem>
784
785 <listitem>
786 <para>Network connection between the CentOS 7 server and the uCPE
787 device WAN port.</para>
788 </listitem>
789
790 <listitem>
791 <para>One uCPE device LAN connected to the laptop using an ethernet
792 cable.</para>
793 </listitem>
794
795 <listitem>
796 <para>The USB is removed from the uCPE device.</para>
797 </listitem>
798
799 <listitem>
800 <para>The uCPE device powered off.</para>
801 </listitem>
802 </itemizedlist>
803 </section>
804 </section>
805
806 <section id="mg_ucpe_devices">
807 <title>Management of uCPE Devices</title>
808
809 <para>When the installation is complete the uCPE Device can be connected
810 to uCPE Manager.</para>
811
812 <section id="add_offline_config">
813 <title>Add a default Offline Configuration</title>
814
815 <para>Zero Touch Provisioning is always turned on when a uCPE device
816 connects to the uCPE Manager. To enable it in the uCPE Manager, an
817 offline configuration needs to be registered for Day-0
818 configuration.</para>
819
820 <note>
821 <para>Day-0 configuration is a software lifecycle term referring to
822 early configurations to put the uCPE device in an active state. Day-1
823 Configurations are applied after Day-0 and set the uCPE device and its
824 service in an active state. Day-2 Configurations are live
825 configurations on the uCPE and its service, applied after the uCPE
826 device and its service have been activated.</para>
827 </note>
828
829 <para>The offline configuration consists of data and parameters that are
830 meant to be automatically set when a uCPE device connects to the uCPE
831 Manager for the first time. The configuration is typically focused on
832 setting up the network management of the uCPE device, e.g. configuring
833 network interfaces, WAN and LAN networking and service chains.</para>
834
835 <para>For this base configuration, the offline configuration will be
836 left blank. The blank offline configuration can be filled with
837 user-specific values and data once the service is created, which is done
838 after installation is complete.</para>
839
840 <note>
841 <para>If the offline configuration is not configured, an alarm will be
842 raised: <literal>Day-0 Config:ZTP:Major</literal> when the uCPE device
843 tries to connect to uCPE Manager, informing the user that the ZTP
844 setup failed for the uCPE device.</para>
845 </note>
846
847 <para><emphasis role="bold">To create an offline
848 configuration</emphasis><orderedlist>
849 <listitem>
850 <para>In a browser access the uCPE Manager, then
851 <literal>Applications</literal>-&gt;<literal>Offline
852 Config</literal>.</para>
853 </listitem>
854
855 <listitem>
856 <para>Create a new offline configuration in the GUI by clicking
857 <literal>Add</literal> and filling in the mandatory fields:
858 <literal>name</literal>, <literal>deviceVersion</literal> and
859 <literal>deviceId</literal>.</para>
860
861 <para>The name is user defined and can be set to any unique text
862 string identifying the configuration. The deviceVersion must match
863 the Enea NFV Access version of the uCPE device and the deviceId
864 must be set to the previously set identifier of the uCPE (uCPE
865 Identifier).</para>
866 </listitem>
867 </orderedlist></para>
868 </section>
869
870 <section id="add_ucpe_mg">
871 <title>Add a uCPE device to the Management System</title>
872
873 <para>The uCPE Manager will periodically poll the uCPE device based on
874 the IP address broadcasted by the uCPE device, attempting to establish a
875 management connection.</para>
876
877 <para>For the connection to succeed, add the uCPE device running the NFV
878 Access Run Time Platform to the management system:
879 <literal>Devices</literal> -&gt; <literal>Manage</literal> -&gt;
880 <literal>Add</literal>. Supply information about the uCPE device and set
881 the parameters that will be used to connect to it.</para>
882
883 <para>The relevant parameters are:</para>
884
885 <itemizedlist>
886 <listitem>
887 <para><emphasis role="bold">Type.</emphasis> The type of device to
888 be added, i.e Enea universal CPE.</para>
889 </listitem>
890
891 <listitem>
892 <para><emphasis role="bold">Name.</emphasis> The name by which the
893 uCPE device is referred to in the uCPE Manager.</para>
894 </listitem>
895
896 <listitem>
897 <para><emphasis role="bold">SSH Port.</emphasis> The NETCONF Port
898 used for communications. Default is set to 830.</para>
899 </listitem>
900
901 <listitem>
902 <para><emphasis role="bold">SSH User Name.</emphasis> The user name
903 for SSH connectivity. Default user is root.</para>
904 </listitem>
905
906 <listitem>
907 <para><emphasis role="bold">SSH Password.</emphasis> Leave this
908 blank.</para>
909 </listitem>
910
911 <listitem>
912 <para><emphasis role="bold">Device Calls Home.</emphasis> This
913 checkbox indicates the direction of uCPE device communications. For
914 a base configuration, leave this flag unchecked.</para>
915 </listitem>
916
917 <listitem>
918 <para><emphasis role="bold">Device ID.</emphasis> The unique
919 identifier of the uCPE device.</para>
920 </listitem>
921 </itemizedlist>
922 </section>
923
924 <section id="boot_device_add_map">
925 <title>Booting the uCPE device and adding it to the Map</title>
926
927 <para>When connectivity is established with the uCPE Manager and a uCPE
928 device is already registered with a matching <literal>Device
929 ID</literal>, the installation is complete, and the connection is
930 established.</para>
931
932 <note>
933 <para>In case of failure due to a misconfiguration or if a uCPE device
934 does not appear in the uCPE Manager, a reinstallation is needed .The
935 user should remove all WAN cables, reinsert the USB stick, reattach
936 the laptop, reboot the uCPE device and then access the Web-installer
937 (<literal>http://172.16.1.1</literal>). If the uCPE device does not
938 appear in the uCPE Manager then a reinstallation is needed.</para>
939 </note>
940
941 <para>When a uCPE device is registered it can be manually added to the
942 map for overview. Right-click on the map and select <literal>Place
943 Device</literal> to put the uCPE device on the map.</para>
944 </section>
945 </section>
946
947 <section id="ucpe_monitor">
948 <title>uCPE Device Monitorization and Control</title>
949
950 <para>Once the uCPE device is connected to the uCPE Manager, it is ready
951 for central management. Two important functions available in the uCPE
952 Manager GUI are alarm checking and resource allocation.</para>
953
954 <section id="check_alarms">
955 <title>Checking Alarms</title>
956
957 <para>The uCPE Manager dashboard presents alarms in a specific window on
958 the front page.</para>
959
960 <para>An alarm can be easily triggered by disconnecting and reconnecting
961 the WAN ethernet cable from the uCPE device. The management system will
962 detect the broken link and raise an alarm: <literal>Device
963 Disconnected::Critical</literal>.</para>
964
965 <para>A separate Alarm Management window can be accessed from the uCPE
966 Manager menu for in-depth access and programming of Alarms and
967 Events.</para>
968 </section>
969
970 <section id="ck_resource_alloc">
971 <title>Checking uCPE device Resource Allocation</title>
972
973 <para>When the uCPE device is connected to the uCPE Manager it is of
974 interest to check the amount of hardware resources in use.</para>
975
976 <para>To check CPU, RAM and disk utilization simply select the uCPE
977 device and click the <literal>Virtual Machines</literal> tab in the map
978 view. The same view will show active VNFs running on the uCPE device
979 once instantiated.</para>
980 </section>
981
982 <section id="access_device_cli">
983 <title>Accessing the uCPE device CLI</title>
984
985 <para>As a final check to make sure the uCPE device was installed
986 correctly, access its Linux CLI by marking the uCPE device on the map
987 and selecting <literal>SSH</literal> from the panel. A new window will
988 appear for CLI access. The default user and password are
989 <literal>root</literal> and blank, respectively.</para>
990
991 <para>The Enea NFV Access CLI is a pure Linux CLI providing access to
992 standard Linux CLI commands. The CLI is a central feature for running
993 custom scripting.</para>
994 </section>
995 </section>
996</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/introduction.xml b/doc/book-enea-nfv-access-getting-started/doc/introduction.xml
index 2009672..7a2f01e 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/introduction.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/introduction.xml
@@ -2,84 +2,270 @@
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="intro_ucpe"> 4<chapter id="intro_ucpe">
5 <title>Introduction</title> 5 <title>Overview</title>
6 6
7 <para>Enea NFV Access for universal Customer Premise Equipment (uCPE) is a 7 <para>This document describes the Enea NFV Access and provides installation
8 virtualization and management platform, which allows end-users to introduce, 8 steps for deploying a base configuration in order to create:</para>
9 instantiate, and run third-party VNFs onto their systems. It is comprised of
10 two major components working in close cooperation:</para>
11 9
12 <itemizedlist> 10 <itemizedlist>
13 <listitem> 11 <listitem>
14 <para>The Enea NFV Access Run-Time Platform, which acts as the host for 12 <para>A functional uCPE Management installation ready to manage uCPE
15 Virtualized Network Functions (VNFs) and provides management over 13 devices.</para>
16 NETCONF.</para>
17 </listitem> 14 </listitem>
18 15
19 <listitem> 16 <listitem>
20 <para>The Enea uCPE Manager, a solution that runs on an external server, 17 <para>One or several managed uCPE devices, ready to host network
21 providing VNF Management functionality and managing large numbers of 18 services, using one wired WAN and one wired LAN connection.</para>
22 uCPEs.</para> 19 </listitem>
20
21 <listitem>
22 <para>One laptop accessing both the uCPE Manager and the uCPE
23 device.</para>
23 </listitem> 24 </listitem>
24 </itemizedlist> 25 </itemizedlist>
25 26
26 <section id="nfv_access"> 27 <para>Extended deployment and configuration options are also detailed in the
27 <title>Enea NFV Access Run Time Platform</title> 28 following chapters.</para>
29
30 <section id="ena_solution">
31 <title>Enea NFV Access</title>
32
33 <para>Enea NFV Access for universal Customer Premise Equipment (uCPE) is a
34 virtualization and management platform, which allows end-users to onboard,
35 instantiate, and run third-party VNFs onto their systems. It is comprised
36 of two major components working in close cooperation:</para>
37
38 <itemizedlist>
39 <listitem>
40 <para>The Enea NFV Access Run-Time Platform, which acts as the host
41 for Virtualized Network Functions (VNFs) and provides management over
42 NETCONF.</para>
43 </listitem>
44
45 <listitem>
46 <para>The Enea uCPE Manager, a solution that runs on an external
47 server, used for VNF Management and managing large numbers of uCPE
48 devices.</para>
49 </listitem>
50 </itemizedlist>
51
52 <para>In addition, Enea NFV Access also includes a software framework for
53 Automation and Testing (AFTH). More information can be found in
54 <xi:include href="../../s_docbuild/olinkdb/pardoc-common.xml"
55 xmlns:xi="http://www.w3.org/2001/XInclude"
56 xpointer="element(book_enea_nfv_access_auto_fw_th_user_guide/1)" />.</para>
57
58 <para> Details concerning release content, including documentation
59 structure, are provided in the <xi:include
60 href="../../s_docbuild/olinkdb/pardoc-common.xml"
61 xmlns:xi="http://www.w3.org/2001/XInclude"
62 xpointer="element(book_enea_nfv_access_release_info/1)" /> manual included
63 with your release.</para>
64
65 <section id="nfv_access">
66 <title>Enea NFV Access Run Time Platform</title>
67
68 <para>The Enea NFV Access Run Time Platform is a lightweight,
69 multi-architecture virtualization platform, supporting Virtual Machines
70 (KVM / QEMU) and container(s) (Docker). Designed for a low footprint and
71 fast boot by only providing essential functionality.</para>
72
73 <para>The NFV Access virtualized data plane has DPDK and accelerated OVS
74 as its primary components. The data plane is highly optimized for
75 scenarios where high throughput and low latency are needed.</para>
28 76
29 <para>Enea NFV Access Run Time Platform is a lightweight, 77 <para>VNF Runtime Management, orchestration integration, and FCAPS are
30 multi-architecture virtualization platform, supporting Virtual Machines 78 provided through NETCONF.</para>
31 (KVM / QEMU) and container(s) (Docker). Designed for a low footprint and
32 fast boot by only providing essential functionality.</para>
33 79
34 <para>The NFV Access virtualized data plane has DPDK and accelerated OVS 80 <figure>
35 as its primary components. The data plane is highly optimized for 81 <title>VNF Space</title>
36 scenarios where high throughput and low latency are needed.</para>
37 82
38 <para>VNF Runtime Management, orchestration integration, and FCAPS are 83 <mediaobject>
39 provided through EdgeLink NETCONF.</para> 84 <imageobject>
85 <imagedata align="center" contentwidth="600"
86 fileref="images/vnf_space.png" />
87 </imageobject>
88 </mediaobject>
89 </figure>
90 </section>
40 91
41 <figure> 92 <section id="ucpe_manager">
42 <title>VNF Space</title> 93 <title>Enea uCPE Manager</title>
43 94
44 <mediaobject> 95 <para>The Enea uCPE Manager is a control center application providing a
45 <imageobject> 96 full FCAPS and VNF management experience through a GUI and REST API. It
46 <imagedata align="center" fileref="images/vnf_space.png" scale="80" /> 97 can be deployed on a host or a virtual machine running 64-bit CentOS 7
47 </imageobject> 98 on an x86 platform. The uCPE Manager uses a southbound NETCONF protocol
48 </mediaobject> 99 to connect and manage uCPE devices.</para>
49 </figure> 100
101 <para>The Enea uCPE Manager provides the following key features:</para>
102
103 <itemizedlist>
104 <listitem>
105 <para>VNF Onboarding</para>
106 </listitem>
107
108 <listitem>
109 <para>VNF Management</para>
110 </listitem>
111
112 <listitem>
113 <para>FCAPS</para>
114 </listitem>
115
116 <listitem>
117 <para>Zero Touch Provisioning</para>
118 </listitem>
119
120 <listitem>
121 <para>Alarms / Events management and monitoring</para>
122 </listitem>
123 </itemizedlist>
124 </section>
50 </section> 125 </section>
51 126
52 <section id="ucpe_manager"> 127 <section id="def_and_acr">
53 <title>Enea uCPE Manager</title> 128 <title>Definitions and Acronyms</title>
54 129
55 <para>Enea uCPE Manager is a control center application providing a full 130 <section id="definitions">
56 FCAPS and VNF management experience through a GUI and REST API. It can be 131 <title>Definitions</title>
57 deployed on a host or a virtual machine running 64-bit CentOS on an x86
58 platform. The uCPE Manager uses a southbound EdgeLink NETCONF protocol to
59 connect and manage uCPE devices.</para>
60 132
61 <para>Enea uCPE Manager provides the following key features:</para> 133 <table>
134 <title>Definitions</title>
62 135
63 <itemizedlist> 136 <tgroup cols="2">
64 <listitem> 137 <colspec align="left" colname="1" colwidth="1*" />
65 <para>VNF On-boarding</para>
66 </listitem>
67 138
68 <listitem> 139 <colspec align="left" colname="2" colwidth="3*" />
69 <para>VNF Management</para>
70 </listitem>
71 140
72 <listitem> 141 <tbody>
73 <para>FCAPS</para> 142 <row>
74 </listitem> 143 <entry>Enea NFV Access</entry>
75 144
76 <listitem> 145 <entry>The Enea NFV Access Run Time Platform and the uCPE
77 <para>Zero Touch Provisioning</para> 146 Manager.</entry>
78 </listitem> 147 </row>
79 148
80 <listitem> 149 <row>
81 <para>Alarms / Events management and monitoring</para> 150 <entry>Enea NFV Access Run Time Platform</entry>
82 </listitem> 151
83 </itemizedlist> 152 <entry>A lightweight, multi-architecture virtualization
153 platform, supporting Virtual Machines.</entry>
154 </row>
155
156 <row>
157 <entry>Enea uCPE Manager</entry>
158
159 <entry>Enea Universal Customer Premises Equipment
160 Manager.</entry>
161 </row>
162
163 <row>
164 <entry>PCI Passthrough</entry>
165
166 <entry>PCI Passthrough allows for use of a physical PCI device,
167 e.g. a network card inside a VM. If you "PCI passthrough" a
168 device, the device is not available to the host anymore.</entry>
169 </row>
170
171 <row>
172 <entry>uCPE device</entry>
173
174 <entry>A whitebox running the Enea NFV Access Run Time
175 Platform.</entry>
176 </row>
177 </tbody>
178 </tgroup>
179 </table>
180 </section>
181
182 <section id="acronyms">
183 <title>Acronyms</title>
184
185 <table>
186 <title>Acronyms</title>
187
188 <tgroup cols="2">
189 <colspec align="left" colname="1" colwidth="1*" />
190
191 <colspec align="left" colname="2" colwidth="3*" />
192
193 <tbody>
194 <row>
195 <entry>API</entry>
196
197 <entry>Application Programming Interface.</entry>
198 </row>
199
200 <row>
201 <entry>DPDK</entry>
202
203 <entry>Data Plane Development Kit.</entry>
204 </row>
205
206 <row>
207 <entry>EFI</entry>
208
209 <entry>Extensible Firmware Interface.</entry>
210 </row>
211
212 <row>
213 <entry>FCAPS</entry>
214
215 <entry>Fault-management, Configuration, Accounting, Performance
216 and Security.</entry>
217 </row>
218
219 <row>
220 <entry>NETCONF</entry>
221
222 <entry>Network Configuration Protocol.</entry>
223 </row>
224
225 <row>
226 <entry>NFV</entry>
227
228 <entry>Network Functions Virtualization.</entry>
229 </row>
230
231 <row>
232 <entry>OVS</entry>
233
234 <entry>Open vSwitch.</entry>
235 </row>
236
237 <row>
238 <entry>UEFI</entry>
239
240 <entry>Unified Extensible Firmware Interface.</entry>
241 </row>
242
243 <row>
244 <entry>SR-IOV</entry>
245
246 <entry>Single Root Input/Output Virtualization.</entry>
247 </row>
248
249 <row>
250 <entry>PCI</entry>
251
252 <entry>Peripheral Component Interconnect.</entry>
253 </row>
254
255 <row>
256 <entry>REST</entry>
257
258 <entry>Representational State Transfer.</entry>
259 </row>
260
261 <row>
262 <entry>VNF</entry>
263
264 <entry>Virtual Network Function.</entry>
265 </row>
266 </tbody>
267 </tgroup>
268 </table>
269 </section>
84 </section> 270 </section>
85</chapter> 271</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/log_collector.xml b/doc/book-enea-nfv-access-getting-started/doc/log_collector.xml
new file mode 100644
index 0000000..410e692
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/log_collector.xml
@@ -0,0 +1,392 @@
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 uCPE
7 Manager. The following describe how the log collection mechanism
8 works.</para>
9
10 <section id="log_collect_ucpem">
11 <title>Log collecting using the uCPE Manager</title>
12
13 <para>The uCPE Manager allows for collection of the relevant logs from the
14 GUI. Collect the necessary log files and system details, then create an
15 archive (a tar file) on the uCPE device in the
16 <filename>/var/odm/log/archives</filename> folder:</para>
17
18 <orderedlist>
19 <listitem>
20 <para>Access <literal>Operations</literal> -&gt; <literal>Collect
21 Debug Logs</literal>.</para>
22 </listitem>
23
24 <listitem>
25 <para>Provide a file name in the new window.</para>
26 </listitem>
27
28 <listitem>
29 <para>Press the <literal>Execute</literal> button.</para>
30
31 <para>A success message is shown in the same window as shown below. At
32 this moment, the process of collecting logs on the uCPE device
33 starts.</para>
34 </listitem>
35
36 <figure>
37 <title>Collecting Debug Logs</title>
38
39 <mediaobject>
40 <imageobject>
41 <imagedata align="center" contentwidth="500"
42 fileref="images/collect_debug_logs.png" />
43 </imageobject>
44 </mediaobject>
45 </figure>
46 </orderedlist>
47
48 <note>
49 <para>It might take some time for the archive to be created. When the
50 operation completes, a "CollectLogsComplete" notification is sent from
51 the uCPE device to the uCPE Manager. This can be viewed in the GUI under
52 the <literal>Faults</literal> -&gt; <literal>Events</literal> toolbar
53 menu.</para>
54
55 <figure>
56 <title>Collecting Debug Logs</title>
57
58 <mediaobject>
59 <imageobject>
60 <imagedata align="center" contentwidth="500"
61 fileref="images/fault_events.png" />
62 </imageobject>
63 </mediaobject>
64 </figure>
65 </note>
66 </section>
67
68 <section id="view_logs">
69 <title>View collected logs</title>
70
71 <para>A list with the archives containing already collected logs will be
72 shown in the <literal>Device File Listing</literal> table:</para>
73
74 <orderedlist>
75 <listitem>
76 <para>Access <literal>Files</literal> -&gt;
77 <literal>Download</literal>.</para>
78 </listitem>
79
80 <listitem>
81 <para>Press the <literal>List</literal> button.</para>
82
83 <figure>
84 <title>Device File Listing Table</title>
85
86 <mediaobject>
87 <imageobject>
88 <imagedata align="center" contentwidth="500"
89 fileref="images/archive_list.png" />
90 </imageobject>
91 </mediaobject>
92 </figure>
93 </listitem>
94 </orderedlist>
95
96 <note>
97 <para>If the filename you specified does not appear, it might still be
98 in the process of creation. Click on the <literal>Refresh</literal> icon
99 at the bottom of the table until you can see the desired file
100 listing.</para>
101 </note>
102 </section>
103
104 <section id="download_fr_dev">
105 <title>Downloading Logs from the uCPE Device</title>
106
107 <para>This option transfers a debug file archive from the uCPE device to
108 uCPE Manager machine.</para>
109
110 <orderedlist>
111 <listitem>
112 <para>Access <literal>Files</literal> -&gt;
113 <literal>Download</literal>.</para>
114 </listitem>
115
116 <listitem>
117 <para>Press the <literal>List</literal> button.</para>
118 </listitem>
119
120 <listitem>
121 <para>In the <literal>Device File Listing</literal> table, select the
122 archive you want to download from the uCPE device to uCPE
123 Manager.</para>
124 </listitem>
125
126 <listitem>
127 <para>Press the <literal>Download from Device</literal> button.</para>
128
129 <para>The archive will be downloaded from the uCPE device and stored
130 on the uCPE Machine.</para>
131 </listitem>
132 </orderedlist>
133
134 <note>
135 <para>The archive will not be deleted from the uCPE device after
136 download.</para>
137 </note>
138 </section>
139
140 <section id="download_logs_locally">
141 <title>Downloading collected logs locally</title>
142
143 <para>This option downloads a logs archive from the uCPE Manager to a
144 local (user) machine for analysis. The archive must first be available in
145 the uCPE Manager in order to be downloaded.</para>
146
147 <orderedlist>
148 <listitem>
149 <para>Access <literal>Devices</literal> -&gt;
150 <literal>Files</literal>.</para>
151 </listitem>
152
153 <listitem>
154 <para>Select the <literal>Downloaded Files</literal> tab.</para>
155 </listitem>
156
157 <listitem>
158 <para>Select an archive from <literal>Downloaded Files</literal>
159 table.</para>
160 </listitem>
161
162 <listitem>
163 <para>Click the <literal>Download</literal> button.</para>
164
165 <para>The file will be downloaded in browser's download folder.</para>
166
167 <figure>
168 <title>Downloaded Files Table</title>
169
170 <mediaobject>
171 <imageobject>
172 <imagedata align="center" contentwidth="500"
173 fileref="images/download_files.png" />
174 </imageobject>
175 </mediaobject>
176 </figure>
177 </listitem>
178 </orderedlist>
179 </section>
180
181 <section id="delete_log_archive_dev">
182 <title>Deleting a logs archive from a uCPE device</title>
183
184 <para>Use this option when you want to delete unnecessary collected logs
185 on the uCPE device.</para>
186
187 <orderedlist>
188 <listitem>
189 <para>Access <literal>Files</literal> -&gt;
190 <literal>Download</literal>.</para>
191 </listitem>
192
193 <listitem>
194 <para>Press the <literal>List</literal> button.</para>
195 </listitem>
196
197 <listitem>
198 <para>In the <literal>Device File Listing</literal> table, select the
199 archive you want to delete from the uCPE device.</para>
200 </listitem>
201
202 <listitem>
203 <para>Press the <literal>Delete</literal> button.</para>
204
205 <para>The archive will be deleted from the uCPE device and the table
206 will be updated.</para>
207 </listitem>
208 </orderedlist>
209
210 <para>The same can be achieved using these alternative options:</para>
211
212 <orderedlist>
213 <listitem>
214 <para>Access <literal>Operations</literal> -&gt; <literal>Delete Debug
215 Log Archive</literal>.</para>
216 </listitem>
217
218 <listitem>
219 <para>Provide a file name in the new window.</para>
220 </listitem>
221
222 <listitem>
223 <para>Press the <literal>Execute</literal> button.</para>
224
225 <para>A success message is displayed if the file is deleted from the
226 uCPE device correctly.</para>
227 </listitem>
228 </orderedlist>
229 </section>
230
231 <section id="delete_archives_ucpem">
232 <title>Deleting logs archives from the uCPE Manager</title>
233
234 <para>This option deletes a logs archive from the uCPE Manager.</para>
235
236 <orderedlist>
237 <listitem>
238 <para>Access <literal>Devices</literal> -&gt;
239 <literal>Files</literal>.</para>
240 </listitem>
241
242 <listitem>
243 <para>Select the <literal>Downloaded Files</literal> tab.</para>
244 </listitem>
245
246 <listitem>
247 <para>Select an archive from the <literal>Downloaded Files</literal>
248 table.</para>
249 </listitem>
250
251 <listitem>
252 <para>Click the <literal>Delete</literal> button.</para>
253
254 <para>The file will be deleted from the uCPE Manager and the table
255 will be updated.</para>
256 </listitem>
257 </orderedlist>
258
259 <note>
260 <para>Deleting the logs file from the uCPE Manager does not affect the
261 file located on the uCPE device.</para>
262 </note>
263 </section>
264
265 <section id="enable_disable_via_perms">
266 <title>Enabling/Disabling of the Log Collector via Permissions</title>
267
268 <para>To disable the ability to access/download the uCPE device's
269 debug-log files from the uCPE Manager, the appropriate permissions must be
270 changed:</para>
271
272 <orderedlist>
273 <listitem>
274 <para>Access <literal>Security</literal> -&gt;
275 <literal>Configuration</literal>.</para>
276 </listitem>
277
278 <listitem>
279 <para>Click the <literal>Security Groups</literal> tab.</para>
280 </listitem>
281
282 <listitem>
283 <para>Click the desired group.</para>
284 </listitem>
285
286 <listitem>
287 <para>Click the <literal>Permissions</literal> tab on the right
288 side.</para>
289 </listitem>
290
291 <listitem>
292 <para>Click the <literal>Devices</literal> tab like in the image
293 below.</para>
294 </listitem>
295
296 <listitem>
297 <para>Change the <literal>Device File Management</literal> option to
298 <literal>none</literal> to disable the feature.</para>
299 </listitem>
300 </orderedlist>
301
302 <figure>
303 <title>Device File Management</title>
304
305 <mediaobject>
306 <imageobject>
307 <imagedata align="center" contentwidth="500"
308 fileref="images/dev_file_mg.png" />
309 </imageobject>
310 </mediaobject>
311 </figure>
312 </section>
313
314 <section id="download_ucpemg_logs">
315 <title>Downloading uCPE Manager logs</title>
316
317 <para>Often, sending the uCPE Manager logs together with collected uCPE
318 device logs to the support team provides important information for
319 troubleshooting (especially in cases of connectivity issues with the uCPE
320 device and error popups).</para>
321
322 <para>uCPE Manager log files are located in
323 <filename>application/logs/</filename> in the uCPE Manager's installation
324 folder (e.g.<filename>/opt/ems/ucpemanager/application/logs</filename>).
325 They can be copied from that location, or they can be downloaded using the
326 uCPE Manager GUI by performing the following:</para>
327
328 <orderedlist>
329 <listitem>
330 <para>Access <literal>Test</literal> -&gt; <literal>Debug
331 Settings</literal> and select the <literal>Log Files</literal>
332 tab.</para>
333 </listitem>
334
335 <listitem>
336 <para>Select the desired log file
337 (<filename>ucpemanager.log</filename> or
338 <filename>watchdog.log</filename>) and press the
339 <literal>Download</literal> button.</para>
340 </listitem>
341
342 <listitem>
343 <para>A new (blank) popup window opens and the file is downloaded
344 locally. This popup can be closed after the download.</para>
345 </listitem>
346
347 <listitem>
348 <para>Repeat steps 2. And 3. Until all the desired log files have been
349 downloaded</para>
350 </listitem>
351 </orderedlist>
352
353 <figure>
354 <title>Debug Settings</title>
355
356 <mediaobject>
357 <imageobject>
358 <imagedata align="center" contentwidth="500"
359 fileref="images/debug_settings.png" />
360 </imageobject>
361 </mediaobject>
362 </figure>
363 </section>
364
365 <section id="log_collect_no_ucpem">
366 <title>Log collecting without using the uCPE Manager</title>
367
368 <para>Log collection from uCPE Devices can also be done when there is no
369 uCPE Manager connection. A SSH connection to uCPE Device is needed for use
370 of the log collector script, which can be found in the uCPE Device file
371 system in <literal>/usr/local/enea/</literal>.</para>
372
373 <para>The Log collector script takes relevant information about the system
374 and collects it in an archive:</para>
375
376 <programlisting>./log-collector.sh -p &lt;LOG_PATHh&gt; -n &lt;ARCHIVE_NAME&gt;</programlisting>
377
378 <para>Where <literal>-p</literal> is the path where the log archive will
379 be saved, <literal>-n</literal> is the archive name.</para>
380
381 <note>
382 <para>If <literal>-p</literal> is not provided, the default path will be
383 used: <literal>/var/logcollector</literal>. If <literal>-n</literal> is
384 not provided, the default name will be used:
385 <filename>log_archive_&lt;timestamp&gt;.tar.gz</filename>.</para>
386 </note>
387
388 <para>To access the help menu of the script:</para>
389
390 <programlisting>./log-collector.sh -h</programlisting>
391 </section>
392</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/net_config_options.xml b/doc/book-enea-nfv-access-getting-started/doc/net_config_options.xml
new file mode 100644
index 0000000..4c11b7c
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/net_config_options.xml
@@ -0,0 +1,740 @@
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 uCPE
6 Manager 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 uCPE Manager, from the uCPE device. The
13 Device Call Home option is required when deploying a uCPE device behind
14 NAT since the IP address of the uCPE device is hidden for the uCPE
15 Manager.</para>
16
17 <para>Enable Device Call Home by marking the Device Call Home checkbox
18 when registering the uCPE device in uCPE Manager. When using this
19 mechanism, the device will initiate a connection to the uCPE Manager for
20 NETCONF traffic (over SSH), while the uCPE Manager waits for a device
21 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 <literal>Configuration</literal> -&gt; <literal>DPDK</literal> and
47 deselect <literal>Enable DPDK</literal> to disable the DPDK.</para>
48
49 <note>
50 <para>Disabling the DPDK cannot be done after other network
51 configurations have been made.</para>
52 </note>
53
54 <para>In <literal>Configuration</literal> -&gt; <literal>DPDK</literal>
55 it is also possible to configure DPDK resources such as:</para>
56
57 <itemizedlist>
58 <listitem>
59 <para><emphasis role="bold">LCore Mask</emphasis>. Allocated cores
60 for DPDK management functions (CPU core bitmask). Default:
61 0x2.</para>
62 </listitem>
63
64 <listitem>
65 <para><emphasis role="bold">PMD CPU Mask</emphasis>. Allocated cores
66 for DPDK packet processing (CPU core bitmask). Default: 0x4.</para>
67 </listitem>
68
69 <listitem>
70 <para><emphasis role="bold">Socket Memory</emphasis>. Allocated
71 memory to use. Default: 1494.</para>
72 </listitem>
73 </itemizedlist>
74 </section>
75
76 <section id="config_ext_interfaces">
77 <title>Configure External Interfaces</title>
78
79 <para>Once a management connection with the uCPE device has been
80 established by using any of the supported methods, the virtualization
81 networking infrastructure can be configured either manually or by using
82 Zero Touch Provisioning.</para>
83
84 <para>Available network interfaces can be added to the management
85 system, for use by the networking virtualization infrastructure.</para>
86
87 <para>In order to make physical network interfaces available to the
88 virtualization infrastructure and VNFs, they must be configured into the
89 management system.</para>
90
91 <para>To add an interface into the uCPE Manager, select the uCPE device,
92 then from the top toolbar select <literal>Configuration -&gt; External
93 Interfaces -&gt; Configuration -&gt; Add</literal>. The available
94 Interface types are detailed below.</para>
95
96 <section id="dpdk_interface_type">
97 <title>DPDK Interface Type</title>
98
99 <para>Configuring a physical interface in DPDK mode will require a
100 DPDK-based application (e.g. OVS-DPDK) in order to access and use the
101 interface. An interface set as DPDK can be attached to an OVS-DPDK
102 bridge.</para>
103
104 <note>
105 <para>Make sure the <literal>Enable DPDK</literal> checkbox is
106 selected in <literal>Device -&gt; Configuration -&gt;
107 DPDK</literal>, otherwise no interface can be assigned as
108 DPDK.</para>
109 </note>
110
111 <para>To add a DPDK interface under the management system, set
112 appropriate values for the following fields:</para>
113
114 <itemizedlist>
115 <listitem>
116 <para>Source: name of the physical interface.</para>
117 </listitem>
118
119 <listitem>
120 <para>Type: dpdk</para>
121 </listitem>
122
123 <listitem>
124 <para>Networking-type: dpdk</para>
125 </listitem>
126
127 <listitem>
128 <para>Dpdk-type: the kernel module that allows user space access
129 to the physical interface. Either the <literal>vfio-pci</literal>
130 (most commonly used type) or the <literal>igb_uio</literal> driver
131 can be used.</para>
132 </listitem>
133 </itemizedlist>
134 </section>
135
136 <section id="sriov_interface_type">
137 <title>SR-IOV Interface Type</title>
138
139 <para>SR-IOV technology allows for the creation of a number of virtual
140 functions on the host interface, which can be used by VNFs running on
141 the uCPE device.</para>
142
143 <para>For SR-IOV mode configuration, the user must set values for the
144 following fields:</para>
145
146 <itemizedlist>
147 <listitem>
148 <para>Source: name of the physical interface.</para>
149 </listitem>
150
151 <listitem>
152 <para>Type: sr-iov</para>
153 </listitem>
154
155 <listitem>
156 <para>Networking-type: srIov</para>
157 </listitem>
158
159 <listitem>
160 <para>sriov-mode: adapter-pool</para>
161 </listitem>
162
163 <listitem>
164 <para>sriov-num-vfs: the number of virtual functions to
165 create.</para>
166 </listitem>
167 </itemizedlist>
168 </section>
169
170 <section id="standard_interface_type">
171 <title>Standard Interface Type</title>
172
173 <para>Some of the physical network interfaces available on a uCPE
174 device, including Ethernet interfaces, do not have DPDK or SR-IOV
175 support. Instead, the Linux kernel driver has to be used. Wi-Fi and
176 4G/LTE modems can also be configured and used for virtualization
177 infrastructure and VNFs.</para>
178
179 <para>To add Standard Interfaces under the management system, the user
180 must set values for the following fields:</para>
181
182 <itemizedlist>
183 <listitem>
184 <para>Source: the name of physical interface.</para>
185 </listitem>
186
187 <listitem>
188 <para>Networking-type: standard.</para>
189 </listitem>
190 </itemizedlist>
191 </section>
192
193 <section condition="hidden" id="pci_passthrough_interface_type">
194 <title>PCI Passthrough Interface Type</title>
195
196 <para>For the PCI Passthrough a user does not have to configure a
197 physical interface, instead simply select the PCI address and connect
198 it to a virtual port when the VNF instantiation step is
199 reached.</para>
200 </section>
201
202 <section id="man_configuration">
203 <title>Manual Configuration</title>
204
205 <para>For Manual Configuration of uCPE networking, select the uCPE
206 device first and then <literal>Configuration</literal> -&gt;
207 <literal>External Interfaces</literal>, where one can find a list of
208 available network interfaces and their capabilities.</para>
209
210 <section id="configure_interfaces">
211 <title>Configuring Interfaces</title>
212
213 <para>After networking interfaces have been added to the uCPE
214 Manager, the user can change the interface type (DPDK, SR-IOV,
215 Standard, WAN).</para>
216
217 <note>
218 <para>WAN interfaces, which are configured during the installation
219 of the device, do not need to be added, they will be automatically
220 listed as such in the uCPE Manager when the device
221 connects.</para>
222 </note>
223
224 <figure>
225 <title>Configuration of External Interfaces</title>
226
227 <mediaobject>
228 <imageobject>
229 <imagedata align="center" contentwidth="600"
230 fileref="images/edit_inter_config.png" />
231 </imageobject>
232 </mediaobject>
233 </figure>
234
235 <para><emphasis role="bold">How to Edit the Configuration of an
236 Interface</emphasis></para>
237
238 <orderedlist>
239 <listitem>
240 <para>To edit an interface configuration type from the uCPE
241 Manager, select the uCPE device, then from the top toolbar
242 select the <literal>Configuration</literal> menu then
243 <literal>External Interfaces -&gt; Configuration</literal>. The
244 already configured interfaces are displayed here, as can be seen
245 in the figure above.</para>
246 </listitem>
247
248 <listitem>
249 <para>In order to edit an already configured interface, (as in
250 the example popup shown below, a WAN interface) double click on
251 the desired one and a popup will appear. A different popup
252 appears for each type of interface. From the <literal>Host
253 Interface</literal> window, a user can change the networking
254 type and the IP address assignment:</para>
255
256 <figure>
257 <title>Editing an Interface</title>
258
259 <mediaobject>
260 <imageobject>
261 <imagedata align="center" contentwidth="450"
262 fileref="images/edit_inter.png" />
263 </imageobject>
264 </mediaobject>
265 </figure>
266 </listitem>
267 </orderedlist>
268
269 <note>
270 <para>The IP address assignment of an interface can be set as
271 static or dynamic for each type of interface.</para>
272 </note>
273 </section>
274
275 <section id="configure_bridges">
276 <title>Configuring Bridges</title>
277
278 <para>After networking interfaces have been added to the uCPE
279 Manager, the user can create the necessary OVS bridges.</para>
280
281 <figure>
282 <title>OVS Bridges</title>
283
284 <mediaobject>
285 <imageobject>
286 <imagedata align="center" contentwidth="600"
287 fileref="images/ovs_bridges_tab.png" />
288 </imageobject>
289 </mediaobject>
290 </figure>
291
292 <para><emphasis role="bold">How to add OVS bridges in the uCPE
293 Manager</emphasis></para>
294
295 <orderedlist>
296 <listitem>
297 <para>Select the uCPE device.</para>
298 </listitem>
299
300 <listitem>
301 <para>Select <literal>Configuration</literal>.</para>
302 </listitem>
303
304 <listitem>
305 <para>Click <literal>OpenvSwitch</literal>.</para>
306 </listitem>
307
308 <listitem>
309 <para>Select the <literal>Bridges</literal> option, then click
310 <literal>Add</literal>.</para>
311 </listitem>
312 </orderedlist>
313
314 <note>
315 <para>Depending on the settings in <literal>Configuration -&gt;
316 OpenVSwitch -&gt; DPDK</literal>, OVS bridges with or without DPDK
317 support will be used on the uCPE device.</para>
318 </note>
319
320 <para>There are three types of bridges which can be created, each
321 one fulfiling a different role.</para>
322
323 <section id="inband_mg_bridge">
324 <title>uCPE In-band Management bridge</title>
325
326 <para>In-band Management refers to a model where both the data
327 plane and control plane flow over the same network path. In some
328 situations (e.g. the uCPE device has only one routable IP
329 address), this is the only option available to both control and
330 configure the uCPE device, while also allowing for data-path
331 traffic to pass over the same physical interface.</para>
332
333 <para>The solution provided by Enea for in-band management is
334 based upon an OpenvSwitch bridge fielding all traffic passing
335 through the WAN physical port. Any standard or DPDK-assigned
336 network interface can be used for the In-Band management
337 bridge.</para>
338
339 <note>
340 <para>The In-band Management bridge must be recreated each time
341 the uCPE Manager IP address is changed.</para>
342 </note>
343
344 <para>To create the In-Band Management bridge, the user must set
345 values for the following fields:</para>
346
347 <itemizedlist>
348 <listitem>
349 <para>name: name of the bridge.</para>
350 </listitem>
351
352 <listitem>
353 <para>ovs-bridge-type: inbandMgmt</para>
354 </listitem>
355 </itemizedlist>
356
357 <note>
358 <para>The first VNF instantiated on the uCPE device must be
359 connected to the In-Band Management bridge and its WAN interface
360 must be configured as the DHCP client.</para>
361 </note>
362 </section>
363
364 <section id="inband_mg_br_vnfs">
365 <title>In-band Management bridge for VNFs</title>
366
367 <para>If VNF management can be done over a dedicated virtual
368 interface, its possible to extend the networking infrastructure
369 configuration to also access the VNF's management interface over
370 the WAN port.</para>
371
372 <para>For this setup, three types of traffic will pass over the
373 WAN physical interface:</para>
374
375 <itemizedlist>
376 <listitem>
377 <para><emphasis role="bold">Device management</emphasis>. Part
378 of the device configuration done by the uCPE Manager.</para>
379 </listitem>
380
381 <listitem>
382 <para><emphasis role="bold">VNF(s) management</emphasis>.
383 Enabling or disabling features of a VNF. E.g.
384 enabling/disabling the firewall or VPN setup.</para>
385 </listitem>
386
387 <listitem>
388 <para><emphasis role="bold">Data-path</emphasis>. All other
389 traffic that is not used in the control plane and needs to
390 reach a LAN network.</para>
391 </listitem>
392 </itemizedlist>
393
394 <para>To create a VNF In-Band Management bridge, the user must set
395 values for the following fields:</para>
396
397 <itemizedlist>
398 <listitem>
399 <para>name: name of the bridge.</para>
400 </listitem>
401
402 <listitem>
403 <para>ovs-bridge-type: vnfMgmt</para>
404 </listitem>
405
406 <listitem>
407 <para>vnf-mgmt-address: select IPv4 as the type and fill in
408 the IP address for management network, e.g 10.0.0.1.</para>
409 </listitem>
410 </itemizedlist>
411
412 <note>
413 <para>VNF management interfaces must be configured in same
414 network as the <literal>vnf-mgmt-address</literal> of the
415 bridge.</para>
416 </note>
417 </section>
418
419 <section id="dataplane_bridge">
420 <title>Data-plane Bridge</title>
421
422 <para>Data-plane bridges are generic bridges used for the VNF
423 data-plane. There are two supported sub-types:</para>
424
425 <itemizedlist>
426 <listitem>
427 <para><emphasis role="bold">communication</emphasis>: allows
428 for VNF communication towards LAN/WAN networks. This bridge
429 type has at least one physical port attached to it.</para>
430 </listitem>
431
432 <listitem>
433 <para><emphasis role="bold">integration</emphasis>: allows for
434 VNF-to-VNF communication (usually for service function
435 chaining). This bridge type does not have any physical port
436 attached.</para>
437 </listitem>
438 </itemizedlist>
439
440 <para>To create a Data-plane bridge, the user must set values for
441 the following fields:</para>
442
443 <itemizedlist>
444 <listitem>
445 <para>name: name of the bridge.</para>
446 </listitem>
447
448 <listitem>
449 <para>ovs-bridge-type: select <literal>communication</literal>
450 or <literal>integration</literal>, depending on intended
451 usage. For communication bridges, physical interfaces can be
452 added to the bridge.</para>
453 </listitem>
454 </itemizedlist>
455 </section>
456 </section>
457 </section>
458
459 <section id="zero_touch_prov">
460 <title>Zero Touch Provisioning - Creating an offline
461 configuration</title>
462
463 <para>Zero-Touch Provisioning (ZTP) refers to the process of when a
464 device starts up for the first time and its initial configuration is
465 pushed down by an external management system, so that it is setup for
466 proper operation without additional manual intervention by an
467 operator. ZTP is an alternative to Manual configuration.</para>
468
469 <para>A variety of operations can occur as part of ZTP such as initial
470 device setup, configuration of managed objects, etc. The goal is to
471 set up a device to the maximum possible extent without forcing an
472 operator to be physically present (initially) to manage the
473 device.</para>
474
475 <para>An offline configuration is usually prepared in advance for the
476 uCPE Manager to setup the virtualization infrastructure on the uCPE
477 device, as soon as a device enrolls into the management system.</para>
478
479 <section id="offline_configuration">
480 <title>Offline Configuration</title>
481
482 <para>The Offline Configuration subsystem is used to pre-populate a
483 configuration for a device that will be brought under management at
484 a future point in time. When creating an offline configuration store
485 a <literal>Device ID</literal> can be specified. This ID uniquely
486 identifies the device to be initialized.</para>
487
488 <para>Alternatively, a wildcard can be used in the <literal>Device
489 ID</literal> field, which results in a configuration being pushed on
490 all uCPE devices upon their initial connection towards the uCPE
491 Manager.</para>
492
493 <para>If the offline configuration is not configured for a uCPE
494 device, an alarm will be raised: <literal>Day-0
495 Config:ZTP:Major</literal>, which occurs when the uCPE device
496 connects to the uCPE Manager informing that the ZTP setup failed for
497 the specific uCPE device.</para>
498
499 <para>To create an offline configuration, from the top toolbar menu
500 select <literal>Applications</literal> -&gt; <literal>Offline
501 Config</literal> -&gt; <literal>Add</literal>. The following fields
502 should be filled:</para>
503
504 <itemizedlist>
505 <listitem>
506 <para>Name: name of the device.</para>
507 </listitem>
508
509 <listitem>
510 <para>Device type: Enea universal CPE.</para>
511 </listitem>
512
513 <listitem>
514 <para>DeviceVersion: <xi:include
515 href="../../s_doceneacommon/doc/eltf_params_updated.xml"
516 xmlns:xi="http://www.w3.org/2001/XInclude"
517 xpointer="element(EneaLinux_REL_VER/1)" /></para>
518 </listitem>
519
520 <listitem>
521 <para>Config Set: uCPE Config</para>
522 </listitem>
523
524 <listitem>
525 <para>Device ID: device ID or a wildcard(*).</para>
526 </listitem>
527
528 <listitem>
529 <para>Device Grouping Tags: a tag to group devices. These tags
530 match the customer tags provided during the installation of the
531 device.</para>
532 </listitem>
533 </itemizedlist>
534
535 <para>The Name is user defined and can be set to any unique text
536 string identifying the configuration. The Device Version will match
537 the Enea NFV Access version of the uCPE device and the Device ID
538 will be set to the previously set identifier of the uCPE
539 device.</para>
540
541 <para>When a device connects to the uCPE Manager for the first time,
542 it checks the device to see if it has been Zero Touch Provisioned
543 (ZTP). If not, it looks for an offline configuration that matches
544 these values, in the following order:</para>
545
546 <itemizedlist>
547 <listitem>
548 <para>The Device ID.</para>
549 </listitem>
550
551 <listitem>
552 <para>The set of tags.</para>
553 </listitem>
554
555 <listitem>
556 <para>A "*" for Device ID (wildcard).</para>
557 </listitem>
558 </itemizedlist>
559
560 <para>If a match is found, the offline configuration is sent to the
561 device as part of Zero-Touch-Provisioning.</para>
562
563 <para>After creating the Offline Config Store, access the device
564 through <literal>Applications</literal> -&gt; <literal>offline
565 config</literal> -&gt; <literal>Config App</literal> and provision
566 it with the required initial configuration. This operation mirrors
567 what happens during manual configuration described
568 previously.</para>
569
570 <note>
571 <para>The ZTP will only be triggered the first time a uCPE device
572 connects to the uCPE Manager. Just changing an offline
573 configuration will not push the new changes to the device. If an
574 offline configuration is changed after uCPE device registration, a
575 factory reset can be executed to force a new ZTP to execute by
576 selecting the device, then <literal>Operations</literal> -&gt;
577 <literal>factory reset</literal>.</para>
578 </note>
579 </section>
580 </section>
581
582 <section id="custom_scripts">
583 <title>Custom Scripts for Custom Networking Configurations</title>
584
585 <para>The custom scripts feature allows users to execute user-defined
586 scripts on the uCPE device at various times.This allows for more
587 flexible and advanced configurations such as a LTE modem
588 configuration, advanced network configurations or OVS flow rule
589 programming at any time.</para>
590
591 <section id="upload_scripts">
592 <title>Uploading Scripts</title>
593
594 <para>The scripts need to be uploaded to the uCPE Manager prior to
595 use. When uploading scripts to the uCPE Manager make sure to select
596 the right script type.</para>
597
598 <para>The following script types are supported:</para>
599
600 <itemizedlist>
601 <listitem>
602 <para><literal>Once-before-startup</literal>. This script will
603 only execute once during the startup.</para>
604 </listitem>
605
606 <listitem>
607 <para><literal>Always-before-startup</literal>. This script will
608 always execute during the startup.</para>
609 </listitem>
610
611 <listitem>
612 <para><literal>Once-after-startup</literal>. This script will
613 only execute once after the system has been started.</para>
614 </listitem>
615
616 <listitem>
617 <para><literal>Always-after-startup</literal>. This script will
618 always execute after the system has been started.</para>
619 </listitem>
620 </itemizedlist>
621
622 <para>Follow the instruction below to upload scripts:</para>
623
624 <orderedlist>
625 <listitem>
626 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
627 Scripts</literal> -&gt; <literal>Configure</literal>.</para>
628 </listitem>
629
630 <listitem>
631 <para>Select <literal>Upload to EMS</literal>.</para>
632 </listitem>
633
634 <listitem>
635 <para>In the <literal>Script Type</literal> menu, select the
636 type the uploaded script should have.</para>
637 </listitem>
638
639 <listitem>
640 <para>Press <literal>Choose File</literal> to select the scripts
641 needed, and then press <literal>Send</literal>.</para>
642 </listitem>
643 </orderedlist>
644 </section>
645
646 <section id="remove_scripts">
647 <title>Removing Scripts</title>
648
649 <para>Follow the instruction below to remove scripts:</para>
650
651 <orderedlist>
652 <listitem>
653 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
654 Scripts</literal> -&gt; <literal>Configure</literal>.</para>
655 </listitem>
656
657 <listitem>
658 <para>Select the script you want to delete from the
659 <literal>Uploaded Scripts</literal> tab and then click
660 <literal>Delete</literal>, which will remove the script
661 immediately from the uCPE Manager.</para>
662 </listitem>
663 </orderedlist>
664 </section>
665
666 <section id="configure_scripts">
667 <title>Configuring Script Location</title>
668
669 <para>The location where the scripts are staged in the uCPE Manager
670 can be chanaged as described below:</para>
671
672 <orderedlist>
673 <listitem>
674 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
675 Scripts</literal> -&gt; <literal>Configure</literal>.</para>
676 </listitem>
677
678 <listitem>
679 <para>Select the <literal>Configuration</literal> tab and
680 specify a new loacation to store the scripts.</para>
681
682 <note>
683 <para>Change the script storage location only if you have many
684 scripts which you would prefer to store on another partition,
685 otherwise leave this configuration as is.</para>
686 </note>
687 </listitem>
688 </orderedlist>
689 </section>
690
691 <section id="run_the_scripts">
692 <title>Running the Scripts</title>
693
694 <para><emphasis role="bold">How to run Custom
695 Scripts</emphasis></para>
696
697 <orderedlist>
698 <listitem>
699 <para>Select <literal>Devices</literal> -&gt; <literal>Custom
700 Scripts</literal> -&gt; <literal>Apply Scripts</literal>.</para>
701 </listitem>
702
703 <listitem>
704 <para>In the <literal>Script Config Screen</literal> pop up,
705 select the devices from the device(s) chooser list on which to
706 run the scripts. Press the <literal>&gt;</literal> button to
707 move the devices to the right side of the chooser, which is the
708 list of devices that will execute the selected scripts.</para>
709 </listitem>
710
711 <listitem>
712 <para>Select the scripts from the list under the device(s)
713 chooser by pressing the <literal>+</literal> button.</para>
714 </listitem>
715
716 <listitem>
717 <para>In the pop-up window, select the scripts from the list. If
718 there are no scripts to select, then there is no script uploaded
719 with that particular type. Upload the script(s) needed and try
720 again.</para>
721 </listitem>
722
723 <listitem>
724 <para>Check the checkbox <literal>Reboot devices</literal> if
725 you want to reboot and execute the scripts at once and then
726 press <literal>ok</literal>.</para>
727
728 <note>
729 <para>The status of execution for the scripts can be seen by
730 opening the <literal>Fault</literal> -&gt;
731 <literal>Events</literal> screen and filtering by device
732 and/or the event name <filename>Custom</filename>.</para>
733 </note>
734 </listitem>
735 </orderedlist>
736 </section>
737 </section>
738 </section>
739 </section>
740</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml b/doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml
new file mode 100644
index 0000000..b3173e6
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml
@@ -0,0 +1,169 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="troubleshooting">
3 <title>Troubleshooting and Recovery</title>
4
5 <para>The following is a small list of possible NFV Access problems, and
6 their solutions. <emphasis role="bold">In all scenarios collect the logs if
7 possible for a later debugging.</emphasis> More information on log
8 collecting can be found in <remark>add an olink to the log collector chapter
9 after the olink update</remark>.</para>
10
11 <para>If you encounter other issues or can't get NFV Access to work
12 successfully after consulting the information below, please use the <olink
13 targetdoc="book_enea_nfv_access_release_info"
14 targetptr="contacting_enea_support">Enea Support team Form, available in the
15 <xi:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
16 xmlns:xi="http://www.w3.org/2001/XInclude"
17 xpointer="element(book_enea_nfv_access_release_info/1)" /></olink> manual
18 downloaded with your release.</para>
19
20 <table>
21 <title>Troubleshooting and Recovery</title>
22
23 <tgroup cols="2">
24 <colspec align="left" />
25
26 <thead>
27 <row>
28 <entry align="center">NFV Access Problem</entry>
29
30 <entry align="center">Solution</entry>
31 </row>
32 </thead>
33
34 <tbody>
35 <row>
36 <entry>The uCPE Device cannot boot after an upgrade.</entry>
37
38 <entry><orderedlist>
39 <listitem>
40 <para>Perform a hardware reboot of the uCPE Device and select
41 the previous NFV Access image from the GRUB menu. This action
42 assumes physical access to the uCPE device.</para>
43 </listitem>
44
45 <listitem>
46 <para>Reinitiate the Upgrade procedure according to
47 <remark>(Link to NFV Access Getting Started -Device
48 Upgrade)</remark>.</para>
49 </listitem>
50 </orderedlist></entry>
51 </row>
52
53 <row>
54 <entry>After a failed uCPE device upgrade the previous NFV Access
55 image (from the GRUB menu) does not boot.</entry>
56
57 <entry>Reinstall NFV Access on the uCPE device and redeploy the
58 initial configuration and virtualized services, by following the
59 Getting Started Guide.<remark>add link to Install uCPE Device.
60 Retitle it if need be or point to specific chapter in book with
61 olink</remark></entry>
62 </row>
63
64 <row>
65 <entry>The uCPE Manager upgrade fails and a working snapshot is
66 available.</entry>
67
68 <entry>If a working snapshot obtained during a previous Upgrade or
69 Uninstall is available
70 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>):
71 <orderedlist>
72 <listitem>
73 <para>Cleanup the current upgrade attempt with:</para>
74
75 <programlisting>./cleanup.sh /opt/ems</programlisting>
76 </listitem>
77
78 <listitem>
79 <para>Restore the previous installation as described in</para>
80
81 <remark>olink to the section/chapter: link to Restore a
82 previous uCPE Manager Installation</remark>
83 </listitem>
84 </orderedlist></entry>
85 </row>
86
87 <row>
88 <entry>The uCPE Manager upgrade fails and no working snapshot is
89 available.</entry>
90
91 <entry><orderedlist>
92 <listitem>
93 <para>Cleanup the current upgrade attempt with: </para>
94
95 <programlisting>./cleanup.sh /opt/ems</programlisting>
96 </listitem>
97
98 <listitem>
99 <para>Perform a installation with the restore option of a
100 previous uCPE Manager configuration as described in </para>
101
102 <remark>olink to the section/chapter describing: Installing
103 with the restore option.</remark>
104 </listitem>
105 </orderedlist></entry>
106 </row>
107
108 <row>
109 <entry>The uCPE device is booted, the ssh connection is available
110 but the device is not connected to the uCPE Manager.</entry>
111
112 <entry><orderedlist>
113 <listitem>
114 <para>Perform a hardware reboot on the uCPE device to
115 reinitiate the connection mechanism.</para>
116 </listitem>
117
118 <listitem>
119 <para>Use the <literal>Reconnect</literal> button from the
120 uCPE Manager's WEB-UI.</para>
121 </listitem>
122
123 <listitem>
124 <para>If the above actions do not work, reinstall and
125 reconfigure the device using the steps provided in the
126 <remark>Installing the uCPE device (add link)</remark></para>
127 </listitem>
128 </orderedlist></entry>
129 </row>
130
131 <row>
132 <entry>The SSH connection to the device cannot be
133 established.</entry>
134
135 <entry>Perform a hardware reboot on the uCPE device. If the problem
136 is not fixed, reinstall and reconfigure the device using the steps
137 provided in the <remark>Installing the uCPE device (add
138 link)</remark></entry>
139 </row>
140
141 <row>
142 <entry>The VNF Service is not working as expected after
143 reconfiguration (e.g. a VNF chain is malfunctioning).</entry>
144
145 <entry><orderedlist>
146 <listitem>
147 <para>Undo all flows and/or configuration changes in order to
148 move the system to a previously working configuration.</para>
149 </listitem>
150
151 <listitem>
152 <para>Reboot the device using <literal>Operations</literal>
153 -&gt; <literal>Reboot</literal> menu options from within the
154 uCPE Manager.</para>
155 </listitem>
156
157 <listitem>
158 <para>If the above actions do not work, redeploy all services.
159 This is done by cleaning up the existing configuration using:
160 <literal>Operations</literal> -&gt; <literal>Factory
161 Reset</literal> for a specific device and redeploying the VNF
162 services.</para>
163 </listitem>
164 </orderedlist></entry>
165 </row>
166 </tbody>
167 </tgroup>
168 </table>
169</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml b/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
new file mode 100644
index 0000000..4b1a7dc
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml
@@ -0,0 +1,537 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="upgrade_ena">
3 <title>Upgrading NFV Access</title>
4
5 <para>Enea provides regular releases that will require the upgrading of NFV
6 Access components. The uCPE Manager must be upgraded to the new Enea NFV
7 Access version before the uCPE devices are.</para>
8
9 <section id="upgrade_mg">
10 <title>Upgrading the uCPE Manager</title>
11
12 <orderedlist>
13 <listitem>
14 <para>Unzip the
15 <filename>Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
16 folder.</para>
17
18 <para>The directory in which the archive has been unpacked will be
19 denoted as <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
20 </listitem>
21
22 <listitem>
23 <para>Enter <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
24 </listitem>
25
26 <listitem>
27 <para>Run the following command with the root account and change
28 <literal>/opt/ems</literal> to the correct location of the uCPE
29 Manager installation:</para>
30
31 <programlisting>./upgrade.sh /opt/ems \
32Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</programlisting>
33 </listitem>
34 </orderedlist>
35
36 <para>Running this command will:</para>
37
38 <itemizedlist>
39 <listitem>
40 <para>Stop the currently running <literal>ucpemanager</literal>
41 service.</para>
42 </listitem>
43
44 <listitem>
45 <para>Create a compressed file of the <literal>ucpemanager</literal>
46 application folder
47 (<filename>ucpemanager-Back-up-YYYYddMMHHmm.tar.gz</filename>), which
48 contains a snapshot of the existing installation.</para>
49
50 <note>
51 <para>The snapshot file created during the upgrade can be used for
52 restoring the uCPE Manager.</para>
53 </note>
54 </listitem>
55
56 <listitem>
57 <para>Extract the application files from the specified compressed
58 install kit.</para>
59 </listitem>
60
61 <listitem>
62 <para>Start the <literal>ucpemanager</literal> service.</para>
63 </listitem>
64 </itemizedlist>
65
66 <section id="restore_prev_ucpe_install">
67 <title>Restoring a previous uCPE Manager installation</title>
68
69 <para><emphasis role="bold">How to restore a previous uCPE Manager
70 installation</emphasis></para>
71
72 <orderedlist>
73 <listitem>
74 <para>Unzip
75 <filename>Enea_NFV_Access_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename></para>
76 </listitem>
77
78 <listitem>
79 <para>The directory in which the archive has been unpacked will be
80 denoted as <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
81 </listitem>
82
83 <listitem>
84 <para>Copy the snapshot file
85 (<filename>ucpemanager-Backup-YYYYddMMHHmm.tar.gz</filename>)
86 created during a previous uCPE Manager Upgrade or uCPE Manager
87 Uninstall Operation into the
88 <literal>&lt;uCPEM-installdir&gt;</literal> directory.</para>
89 </listitem>
90
91 <listitem>
92 <para>Enter <literal>&lt;uCPEM-installdir&gt;</literal>.</para>
93 </listitem>
94
95 <listitem>
96 <para>Run the following command with the root user and change
97 <literal>/opt/ems</literal> to the correct location of the uCPE
98 Manager installation:</para>
99
100 <programlisting>./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz</programlisting>
101 </listitem>
102 </orderedlist>
103
104 <para>Running this command will:</para>
105
106 <itemizedlist>
107 <listitem>
108 <para>Remove any vestiges of the existing
109 <literal>ucpemanager</literal> service, if they exist.</para>
110 </listitem>
111
112 <listitem>
113 <para>Reinstall the uCPE Manager application on the specified target
114 location, restoring the data in the database and files in the
115 process.</para>
116 </listitem>
117 </itemizedlist>
118
119 <para>The <literal>ucpemanager</literal> service will then start with
120 the older version now running on the system.</para>
121 </section>
122
123 <section id="uninstall_ucpem_install">
124 <title>Uninstalling an existing uCPE Manager installation</title>
125
126 <para><emphasis role="bold">How to uninstall an existing uCPE Manager
127 installation</emphasis></para>
128
129 <orderedlist>
130 <listitem>
131 <para>Navigate to the folder where the uCPE Manager is
132 installed.</para>
133 </listitem>
134
135 <listitem>
136 <para>Run the following command with the root user and change
137 <literal>/opt/ems</literal> to the correct location of the uCPE
138 Manager installation:</para>
139
140 <programlisting>./uninstall.sh /opt/ems</programlisting>
141 </listitem>
142 </orderedlist>
143
144 <para>Running this command will:</para>
145
146 <itemizedlist>
147 <listitem>
148 <para>Stop the currently running <literal>ucpemanager</literal>
149 service.</para>
150 </listitem>
151
152 <listitem>
153 <para>Create a compressed file of the <literal>ucpemanager</literal>
154 application folder:
155 <filename>ucpemanager-Back-up-YYYYddMMHHmm.tar.gz</filename>, which
156 contains a snapshot of the existing installation and functions as a
157 restore point.</para>
158
159 <note>
160 <para>The snapshot file created during the uninstall can be used
161 for restoring the uCPE Manager.</para>
162 </note>
163 </listitem>
164
165 <listitem>
166 <para>Uninstall the <literal>ucpemanager</literal> service, so that
167 it will not startup on reboot.</para>
168 </listitem>
169
170 <listitem>
171 <para>Uninstall the database service.</para>
172 </listitem>
173
174 <listitem>
175 <para>Completely remove the contents of the application and database
176 folders.</para>
177 </listitem>
178 </itemizedlist>
179
180 <para>After these steps, the uCPE Manager is completely removed from the
181 system.</para>
182 </section>
183 </section>
184
185 <section id="upgrade_devices">
186 <title>uCPE device upgrades</title>
187
188 <para>A uCPE device can be upgraded using the uCPE Manager GUI.</para>
189
190 <section id="device_up_process">
191 <title>The uCPE device upgrade process</title>
192
193 <para>The Device Upgrade/Install option performs the following
194 operations to the uCPE device:</para>
195
196 <orderedlist>
197 <listitem>
198 <para><emphasis role="bold">Prepare for upgrade.</emphasis> This
199 stage prepares the files needed for an upgrade.</para>
200 </listitem>
201
202 <listitem>
203 <para><emphasis role="bold">Install file on device.</emphasis> This
204 stage copies the file to the uCPE device.</para>
205 </listitem>
206
207 <listitem>
208 <para><emphasis role="bold">Upgrade Device.</emphasis> This stage
209 upgrades the uCPE device to a newer version.</para>
210 </listitem>
211 </orderedlist>
212 </section>
213
214 <section id="mg_upgrade">
215 <title>Managing the Device Upgrade</title>
216
217 <para>Before an installation or upgrade can be completed, certain
218 configuration data must be set. Files also need to be uploaded to the
219 Device Upgrade image repository to be uploaded to the device.</para>
220
221 <para>Launch the Device Upgrade management console by selecting
222 <literal>Devices</literal> -&gt; <literal>Upgrade</literal> from the top
223 tool-bar. The console will contain the following tabs:</para>
224
225 <itemizedlist>
226 <listitem>
227 <para><literal>Image Library</literal>. To add/delete an
228 image.</para>
229 </listitem>
230
231 <listitem>
232 <para><literal>Upgrade Operations</literal>. See running upgrades,
233 cancel any upgrades in progress, start a uCPE device upgrade.</para>
234 </listitem>
235
236 <listitem>
237 <para><literal>Configuration</literal>. Upgrade configuration
238 parameters.</para>
239 </listitem>
240 </itemizedlist>
241
242 <para>Press Close when the message <literal>File Uploaded
243 Successfully</literal> appears on the File Upload Screen.</para>
244
245 <note>
246 <para>The uCPE Device upgrade is done with image files of type
247 <literal>rootfs.ostree.tar.bz2</literal>, which are available in the
248 <filename>Enea_NFV_Ac-cess_uCPEManager_&lt;version&gt;-build&lt;build_number&gt;.tar.gz</filename>
249 file you downloaded with your release.</para>
250 </note>
251
252 <section id="image_lib">
253 <title>Image Library</title>
254
255 <para><emphasis role="bold">Adding an image to the image
256 repository/library</emphasis><orderedlist>
257 <listitem>
258 <para>Select <literal>Devices</literal> -&gt;
259 <literal>Upgrade</literal>.</para>
260 </listitem>
261
262 <listitem>
263 <para>Select <literal>Add</literal> from the <literal>Image
264 Library</literal> tab to add a new image file.</para>
265 </listitem>
266
267 <listitem>
268 <para>Click on <literal>Choose File</literal> to provide the
269 path to the image file (must be of type
270 <literal>rootfs.os-tree.tar.bz2</literal>).</para>
271 </listitem>
272
273 <listitem>
274 <para>Select the target hardware platform corresponding to the
275 image being uploaded (<literal>xeon-d</literal> or
276 <literal>atom-c3000</literal>).</para>
277 </listitem>
278
279 <listitem>
280 <para>Click <literal>Send</literal> to upload the image to the
281 image repository.</para>
282 </listitem>
283 </orderedlist></para>
284
285 <para><emphasis role="bold">Deleting an image from the image
286 repository</emphasis></para>
287
288 <orderedlist>
289 <listitem>
290 <para>Select <literal>Devices</literal> -&gt;
291 <literal>Upgrade</literal>.</para>
292 </listitem>
293
294 <listitem>
295 <para>Select the image you want to delete from the <literal>Image
296 Library</literal> tab and then click
297 <literal>Delete</literal>.</para>
298 </listitem>
299 </orderedlist>
300 </section>
301
302 <section id="upgrade_options">
303 <title>Upgrade Operations</title>
304
305 <para>The <literal>Upgrade Operations</literal> tab allows a user to
306 manage uCPE device upgrades in the system. It allows the user to see
307 all the upgrades that are currently in progress, as well as listing
308 the completed ones. If an upgrade succeeds or fails, then a row will
309 be added to the completed upgrades table. If one fails, the failure
310 message will be visible in the table.</para>
311
312 <note>
313 <para>The list of completed upgrade tasks resides in the cache
314 memory and will not persist across reboots of the server.</para>
315 </note>
316
317 <para><emphasis role="bold">How to Install/Upgrade a device
318 immediately or schedule the process for later</emphasis><orderedlist>
319 <listitem>
320 <para>Select <literal>Devices</literal> -&gt;
321 <literal>Upgrade</literal>.</para>
322 </listitem>
323
324 <listitem>
325 <para>Select <literal>Upgrade Devices</literal> from the
326 <literal>Upgrade Operations</literal> tab. This will launch a
327 <literal>Multi Device Install Image</literal> screen that will
328 allow the user to install and upgrade more than one uCPE device
329 at a time or upgrade later.</para>
330 </listitem>
331 </orderedlist></para>
332
333 <para>The configurable parameters are:</para>
334
335 <itemizedlist>
336 <listitem>
337 <para><literal>Scheduling</literal>. Click this checkbox if the
338 upgrade will be done later. Schedule the day, hour and minute for
339 when to run the upgrade.</para>
340
341 <note>
342 <para>The hour represents the local uCPE Manager server
343 hour.</para>
344 </note>
345 </listitem>
346
347 <listitem>
348 <para><literal>Description</literal>. An optional description of
349 the operation. It is recommended to add a description so that
350 different upgrades happening simultaneously can be
351 distinguished.</para>
352 </listitem>
353
354 <listitem>
355 <para><literal>Image File</literal>. Click on <literal>Choose
356 Image File</literal> to select the image file.</para>
357 </listitem>
358
359 <listitem>
360 <para><literal>Devices</literal>. The list of uCPE Devices that
361 can accept an image file is populated when the image file is
362 chosen.</para>
363
364 <para>Press the <literal>&gt;</literal> button to move the uCPE
365 devices to the right side of the selector. Those chosen form the
366 list of uCPE devices that will be upgraded.</para>
367 </listitem>
368
369 <listitem>
370 <para>Upgrade Operation. The available options are:</para>
371
372 <itemizedlist>
373 <listitem>
374 <para><literal>Install and Activate</literal>. This will do an
375 image installation as well as an upgrade.</para>
376 </listitem>
377
378 <listitem>
379 <para><literal>Install Only</literal>. This will do an image
380 installation only. The image is copied to the uCPE device, and
381 an upgrade will be done later either at a scheduled time or
382 when the option <literal>Activate Only</literal> is
383 selected.</para>
384 </listitem>
385
386 <listitem>
387 <para><literal>Activate Only</literal>. This will activate an
388 already installed image on the uCPE device.</para>
389 </listitem>
390 </itemizedlist>
391 </listitem>
392 </itemizedlist>
393
394 <note>
395 <para>When the uCPE device activates the upgrade, it will be
396 rebooted automatically.</para>
397 </note>
398 </section>
399
400 <section id="releases_installed">
401 <title>Releases installed on a uCPE device</title>
402
403 <para>The installed releases on a uCPE device can be viewed by
404 selecting the uCPE device first, then from the top toolbar selecting
405 <literal>Configuration</literal> -&gt;
406 <literal>Upgrade</literal>.</para>
407
408 <para>The installed releases on the uCPE device, the release status,
409 release state, <literal>commit-id</literal> and release version will
410 be listed in a table.</para>
411 </section>
412
413 <section id="upgrade_status">
414 <title>uCPE device upgrade status</title>
415
416 <para>The status of the installation and upgrade can be viewed in the
417 <literal>Upgrade Operations</literal> tab. Ongoing or scheduled
418 upgrade operations can be viewed or cancelled.</para>
419
420 <para><emphasis role="bold">To view the status of an installation or
421 upgrade operations</emphasis></para>
422
423 <orderedlist>
424 <listitem>
425 <para>Select <literal>Devices</literal> -&gt;
426 <literal>Upgrade</literal>.</para>
427 </listitem>
428
429 <listitem>
430 <para>Select <literal>Upgrade Operations</literal>. The ongoing
431 operations are listed at the top and a history of failed or
432 successful operations are listed at the bottom.</para>
433 </listitem>
434
435 <listitem>
436 <para>Select an <literal>Active</literal> or <literal>Completed
437 Upgrade Operation</literal> and click the <literal>Device
438 Status</literal> button to see detailed information regarding the
439 upgrade operation, including the uCPE devices involved and
440 information per uCPE device.</para>
441 </listitem>
442 </orderedlist>
443
444 <para><emphasis role="bold">To cancel an upgrade
445 operation</emphasis></para>
446
447 <orderedlist>
448 <listitem>
449 <para>Select <literal>Devices</literal> -&gt;
450 <literal>Upgrade</literal> -&gt; <literal>Upgrade
451 Operations</literal>.</para>
452 </listitem>
453
454 <listitem>
455 <para>Select an operation from the list and press <literal>Cancel
456 Upgrade</literal> and <literal>Confirm</literal>. The operation
457 will then be deleted from the list.</para>
458 </listitem>
459 </orderedlist>
460 </section>
461
462 <section id="config">
463 <title>Configuration</title>
464
465 <note>
466 <para>The default values present in the configuration of each uCPE
467 device are recommended for use. Modifying them is for an Advanced
468 User only.</para>
469 </note>
470
471 <para><emphasis role="bold">How to Configure the uCPE device
472 Upgrade</emphasis><orderedlist>
473 <listitem>
474 <para>Select <literal>Devices</literal> -&gt;
475 <literal>Upgrade</literal>.</para>
476 </listitem>
477
478 <listitem>
479 <para>Select <literal>Configuration</literal>.</para>
480 </listitem>
481
482 <listitem>
483 <para>The configurable parameters are:</para>
484
485 <itemizedlist>
486 <listitem>
487 <para><literal>deviceImageDir</literal>. This is the disk
488 location of the device image repository.</para>
489
490 <note>
491 <para>If no absolute path name is given it is assumed to
492 be relative to the installation directory.</para>
493 </note>
494 </listitem>
495
496 <listitem>
497 <para><literal>maxThreads</literal>. This number dictates
498 how many upgrades the system can manage at one time, either
499 individually launched or launched from the multi-device
500 screens. This value defaults to 20, which means that 20 uCPE
501 devices may be updated at one time.</para>
502 </listitem>
503
504 <listitem>
505 <para><literal>KeepAlive</literal>. This number represents
506 the number of seconds that a thread will be kept alive
507 before it is collected. If multiple installations are
508 occurring, this will keep the thread alive for X seconds
509 before it is released. If not released, it can be used by
510 the internal scheduling system as soon as it has completed
511 an upgrade.</para>
512 </listitem>
513 </itemizedlist>
514 </listitem>
515 </orderedlist></para>
516 </section>
517
518 <section id="related_functionality">
519 <title>Related Functionality for a uCPE device upgrade</title>
520
521 <para>Each uCPE device can receive image files and use them to
522 upgrade. This can be done by selecting the uCPE device in the
523 <literal>System</literal> view and clicking the
524 <literal>Upgrade</literal> button. In the new window, an upgrade image
525 can be chosen from the <literal>Image Files</literal> tab by selecting
526 the image file from the list and clicking the <literal>Install on
527 Device</literal> button.</para>
528
529 <para>Once an image is installed on the uCPE device, the image will be
530 available on the uCPE device and be visible in the
531 <literal>Releases</literal> tab. It can then be selected from the list
532 and the upgrade started by clicking the <literal>Upgrade</literal>
533 button.</para>
534 </section>
535 </section>
536 </section>
537</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-getting-started/doc/vnf_mg.xml b/doc/book-enea-nfv-access-getting-started/doc/vnf_mg.xml
new file mode 100644
index 0000000..545bf99
--- /dev/null
+++ b/doc/book-enea-nfv-access-getting-started/doc/vnf_mg.xml
@@ -0,0 +1,481 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="vnf_mg">
3 <title>VNF Management</title>
4
5 <para>The Enea uCPE Manager is responsible for onboarding, configuring (e.g.
6 CloudInit) and ensuring life cycle management of VNFs that are instantiated
7 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 uCPE Manager VNF
13 Catalogue and preparing it for instantiation (deployment on connected uCPE
14 devices). This is accomplished using the Enea uCPE Manager Onboarding
15 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 uCPE Manager is the
39 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 uCPE Manager</title>
113
114 <para><emphasis role="bold">How to onboard a VNF into the uCPE Manager
115 </emphasis></para>
116
117 <orderedlist>
118 <listitem>
119 <para>Select from the top toolbar <literal>VNF</literal> -&gt;
120 <literal>Descriptors</literal></para>
121 </listitem>
122
123 <listitem>
124 <para>Click the <literal>On-board</literal> button.</para>
125 </listitem>
126
127 <listitem>
128 <para>When prompted by the UI, make sure the <literal>VM
129 Image</literal> radio button at the top of the onboarding screen is
130 selected, it will trigger a popup menu window.</para>
131 </listitem>
132 </orderedlist>
133
134 <para>This window contains data fields where both necessary and optional
135 information about the VNF can be supplied. After doing so, press the
136 Onboard button, the uCPE Manager will create the VNF descriptor and add
137 it to its VNF Catalog.</para>
138
139 <figure>
140 <title>Onboard a VNF</title>
141
142 <mediaobject>
143 <imageobject>
144 <imagedata align="center" contentwidth="600"
145 fileref="images/onboard_a_vnf_image.png" />
146 </imageobject>
147 </mediaobject>
148 </figure>
149
150 <para><emphasis role="bold">Main fields</emphasis></para>
151
152 <itemizedlist>
153 <listitem>
154 <para><emphasis role="bold">VM Image File</emphasis>. This is the
155 Virtual Machine image file for the VNF. Typically, it is a QCOW
156 image. Press <literal>Choose File</literal> and select the image you
157 wish to upload.</para>
158 </listitem>
159
160 <listitem>
161 <para><emphasis role="bold">Image Format</emphasis>. Select the
162 format which matches the image file format.</para>
163 </listitem>
164
165 <listitem>
166 <para><emphasis role="bold">VNF Type Name</emphasis>. This is the
167 name that will be used to identify this VNF. It will be shown in the
168 VNFs list.</para>
169 </listitem>
170
171 <listitem>
172 <para><emphasis role="bold">Description</emphasis>. This field
173 contains any description provided and is only displayed in the GUI
174 tables in the uCPE Manager.</para>
175 </listitem>
176
177 <listitem>
178 <para><emphasis role="bold">Version</emphasis>. This is the version
179 of the current VNF that you are hosting. It's used to distinguish
180 this VNF from other versions of the same type.</para>
181 </listitem>
182
183 <listitem>
184 <para><emphasis role="bold">Memory in MB</emphasis>. This is the
185 amount of memory (in megabytes) that will be provided to this type
186 of VNF when it is instantiated. To determine the value for this
187 field, consult the VNF vendor.</para>
188 </listitem>
189
190 <listitem>
191 <para><emphasis role="bold">Num of CPUs</emphasis>. The number of
192 CPUs that will be dedicated to an instance of this VNF when created.
193 To determine the value for this field, consult the VNF
194 vendor.</para>
195 </listitem>
196
197 <listitem>
198 <para><emphasis role="bold">Storage in GB</emphasis>. How much disk
199 space to provide an instance of this VNF. To determine the value for
200 this field, consult the VNF vendor.</para>
201 </listitem>
202 </itemizedlist>
203
204 <para><emphasis role="bold">Interfaces Tab</emphasis></para>
205
206 <para>Click on the <literal>Interfaces</literal> tab to show the
207 Interfaces table.</para>
208
209 <para>This table will contain the interfaces required by this VNF to be
210 configured, when creating an instance. Consult the VNF vendor to
211 determine which and how many are required. Each interface requires a
212 name, and optionally a description, used only by the uCPE
213 Manager.</para>
214
215 <note>
216 <para>CAUTION: The user MUST conserve the same order for the virtual
217 interfaces during both onboarding and instantiation phases.</para>
218 </note>
219
220 <para><emphasis role="bold">Cloud Init Tab</emphasis></para>
221
222 <para>Click the <literal>Clout Init</literal> tab to provide the
223 Clout-Init configuration. There are three fields that need to be
224 populated:</para>
225
226 <orderedlist>
227 <listitem>
228 <para><emphasis role="bold">Cloud-Init Datasource</emphasis></para>
229
230 <para>To onboard a VNF you must specify the <literal>Cloud-Init
231 Datasource</literal> that the VNF uses. This information is procured
232 from the VNF Vendor. Choose one of the following methods to specify
233 the datasource:</para>
234
235 <itemizedlist spacing="compact">
236 <listitem>
237 <para><emphasis role="bold">None</emphasis>. If there is no
238 datasource.</para>
239 </listitem>
240
241 <listitem>
242 <para><emphasis role="bold">ConfigDrive</emphasis>. This method
243 allows you to provide any number of content-data files
244 containing Cloud-Init data.</para>
245 </listitem>
246
247 <listitem>
248 <para><emphasis role="bold">NoCloud</emphasis>. This is a
249 simpler method that uses only one cloud init file
250 (User-Data).</para>
251 </listitem>
252
253 <listitem>
254 <para><emphasis role="bold">ISO</emphasis>. Pre-cooked
255 cloud-init image. This image must be created by the user
256 according to VNF requirements.</para>
257 </listitem>
258 </itemizedlist>
259 </listitem>
260
261 <listitem>
262 <para><emphasis role="bold">Cloud-Init Disk Type</emphasis></para>
263
264 <para>The <literal>Cloud-Init Disk Type</literal> field must be set
265 to either <literal>Disk</literal>, or <literal>CD-ROM</literal>,
266 depending on what the VNF requires. You can get this information
267 from the VNF Vendor.</para>
268 </listitem>
269
270 <listitem>
271 <para><emphasis role="bold">Content Files Table</emphasis></para>
272
273 <para>The <literal>Content Files Table</literal> is ONLY used if
274 <literal>ConfigDrive</literal> is chosend as the Cloud-Init
275 Datasource. For each content file added, a <literal>Path</literal>
276 must be provided. When the uCPE Manager is used to create an
277 instance for multiple VNFs, the user will be prompted to provide a
278 data file for each entry in this table. Each type of VNF will
279 require different cloud-init files, e.g.: a license file. The data
280 files will be added to the cloud-init image that the user provides
281 at the instantiation of the VNF. If the cloud-init image is not
282 provided, no Cloud-Init Data Source will be created for that VNF and
283 there will be no warning.</para>
284 </listitem>
285 </orderedlist>
286
287 <para>Consult with the VNF vendor to determine what is required for the
288 VNF you are onboarding.</para>
289
290 <para><emphasis role="bold">Properties Tab</emphasis></para>
291
292 <para>In this table, you can enter values for properties that will be
293 used during instantiation of the VNF. The values will augment the
294 default values in the <filename>Domain.XML</filename> file used by
295 <literal>libvirt/virsh</literal> (running in NFV Access) when creating
296 an instance of the VNF. Consult with the VNF Vendor or ENEA support for
297 values needed by specific VNFs.</para>
298
299 <para><emphasis role="bold">Property Values</emphasis></para>
300
301 <itemizedlist>
302 <listitem>
303 <para><literal>numHugePages</literal> defines the number of huge
304 memory pages the VNF uses (for DPDK).</para>
305 </listitem>
306
307 <listitem>
308 <para><literal>vnfMgmtIpAddress</literal>: the IP address of the
309 VNF's management interface, connected to a
310 <literal>vnfMgmt</literal> bridge (e.g. 10.0.0.2).</para>
311 </listitem>
312
313 <listitem>
314 <para><literal>internalMgmtPort</literal>: the VNF's TCP/UDP port
315 used for management (e.g. 443).</para>
316 </listitem>
317
318 <listitem>
319 <para><literal>externalMgmtPort</literal>: the Management port used
320 for external access (e.g. 60001).</para>
321 </listitem>
322 </itemizedlist>
323
324 <note>
325 <para>The last three properties are useful in conjuction with the
326 <literal>vnfMgmt</literal> bridge type. They allow the user to map the
327 internal VNF management port to an external port, useful for VNF
328 configuration from WAN.</para>
329
330 <para>In the previous example, the internal TCP port 443 (HTTPS) was
331 mapped to the external port 60001, which allows the user to access the
332 VNF management port from a web browser e.g.
333 <literal>https://&lt;WAN_IP&gt;:60001</literal>.</para>
334 </note>
335 </section>
336 </section>
337
338 <section id="instantiating_a_vnf">
339 <title>Instantiating a VNF</title>
340
341 <para>When a VNF is onboarded and available in the VNF catalog, it can be
342 instantiated on connected uCPE devices. The configurations provided when
343 the VNF is onboarded, serve as a template for instantiation. Before
344 instantiating any VNF, please make sure the available storage space on the
345 uCPE device is big enough to accommodate the VNF you need to
346 instantiate.</para>
347
348 <para>Follow the instructions below to instantiate a VNF:</para>
349
350 <orderedlist>
351 <listitem>
352 <para>Select from the top toolbar <literal>VNF</literal> -&gt;
353 <literal>Instances</literal></para>
354 </listitem>
355
356 <listitem>
357 <para>Click the <literal>Add</literal> button.</para>
358 </listitem>
359
360 <listitem>
361 <para>Fill out the following mandatory fields:</para>
362
363 <itemizedlist spacing="compact">
364 <listitem>
365 <para>Name: a descriptive name.</para>
366 </listitem>
367
368 <listitem>
369 <para>VNF Type: a list of onboarded VNFs.</para>
370 </listitem>
371
372 <listitem>
373 <para>uCPE Device: the uCPE device to instantiate the VNF
374 on.</para>
375 </listitem>
376
377 <listitem>
378 <para>Networking Configuration:</para>
379
380 <itemizedlist spacing="compact">
381 <listitem>
382 <para>Connect each configured NIC with a bridge, SR-IOV or PCI
383 Passthrough.</para>
384 </listitem>
385
386 <listitem>
387 <para>Set up each NIC with a driver method.</para>
388 </listitem>
389 </itemizedlist>
390
391 <note>
392 <para>All configured NICs must be set up before instantiating a
393 VNF. Failure to do so will end in a failed instantiation.</para>
394 </note>
395 </listitem>
396 </itemizedlist>
397 </listitem>
398
399 <listitem>
400 <para>Add VNF-specific configuration data by uploading a Cloud-Init
401 file (when the Cloud-Init is used).</para>
402 </listitem>
403
404 <listitem>
405 <para>Add any VNF-specific files (e.g license files).</para>
406 </listitem>
407
408 <listitem>
409 <para>Hit the <literal>Create</literal> button to deploy the VNF and
410 run it on the specified uCPE device.</para>
411 </listitem>
412 </orderedlist>
413
414 <para>Selecting the<literal> VNF -&gt; Events</literal> menu will show
415 that the VNF was created and a connection was established.</para>
416 </section>
417
418 <section id="enter_console">
419 <title>Accessing the VNF console</title>
420
421 <para>Once the VNF is deployed, the VNF console can be entered using SSH
422 and virsh commands. The VNF Console is a typical starting point for
423 determining a successful deployment and configuring a VNF beyond Day
424 Zero.</para>
425
426 <orderedlist>
427 <listitem>
428 <para>SSH to the uCPE device from the Enea uCPE Manager
429 (<literal>Device-&gt;SSH</literal>) using:</para>
430
431 <itemizedlist>
432 <listitem>
433 <para>For normal connections: the <literal>Username</literal>
434 (default: root), the <literal>Password</literal> (default: no
435 password), the <literal>Port</literal> (default: 22) and the
436 <literal>Reverse ssh</literal> checkbox: unchecked.</para>
437 </listitem>
438
439 <listitem>
440 <para>For reverse ssh connections: the <literal>Username</literal>
441 (default: root) and the <literal>Reverse ssh</literal> checkbox
442 checked. The port will be automatically choosen by the uCPE
443 Manager in the range defined in the <literal>System -&gt;
444 Configuration -&gt; Reverse SSH</literal> configuration panel. By
445 default, the start port will be <literal>7000</literal> and the
446 maximum number of ports allocated to all devices is 10. Only one
447 port per device is allowed.</para>
448
449 <para>A SSH Tunnel between the uCPE Manager and the device will be
450 created:</para>
451
452 <programlisting>ssh -f -N -T -R &lt; Port &gt; :localhost:22 &lt;uCPE Mgr user&gt;@&lt;uCPE MgrIP&gt;</programlisting>
453
454 <para>The device must be connected to the uCPE Manager for the
455 tunnel to be created. On connection, a normal ssh connection will
456 be made:</para>
457
458 <programlisting>ssh -p &lt;Port&gt; &lt;Username&gt;@localhost</programlisting>
459 </listitem>
460 </itemizedlist>
461 </listitem>
462
463 <listitem>
464 <para>In SSH:</para>
465
466 <orderedlist spacing="compact">
467 <listitem>
468 <para>Use the <command>virsh list</command> command to list all
469 running VNFs and to determine the VNF's instance number.</para>
470 </listitem>
471
472 <listitem>
473 <para>Use the <command>virsh console &lt;instance
474 number&gt;</command> command to enter the VNF-specific
475 console.</para>
476 </listitem>
477 </orderedlist>
478 </listitem>
479 </orderedlist>
480 </section>
481</chapter> \ No newline at end of file
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-10-05 05:00:59 +0000