From d78fae86a57e8847e1c52e12aaf7468ff0227815 Mon Sep 17 00:00:00 2001 From: mrpa Date: Wed, 18 Nov 2020 15:28:24 +0100 Subject: Refactoring of Getting started merging to Develop from branch feature_AP-581. Change-Id: I67474ec6badaa279e8c56fca9bb50aec98de8e5f Signed-off-by: mrpa --- .../doc/advanced_configurations.xml | 465 ++--- .../doc/book.xml | 25 +- .../doc/definitions_and_acronyms.xml | 146 -- .../doc/getting_started_nfv_access.xml | 720 ------- .../doc/getting_started_ucpe_manager.xml | 2097 -------------------- .../doc/images/archive_list.png | Bin 0 -> 87667 bytes .../doc/images/collect_debug_logs.png | Bin 0 -> 47994 bytes .../doc/images/debug_settings.png | Bin 0 -> 32833 bytes .../doc/images/dev_file_mg.png | Bin 0 -> 138952 bytes .../doc/images/download_files.png | Bin 0 -> 79979 bytes .../doc/images/fault_events.png | Bin 0 -> 46986 bytes .../doc/images/prep_deploy.png | Bin 0 -> 125599 bytes .../doc/images/prep_execution.png | Bin 0 -> 127191 bytes .../doc/images/vnf_space.png | Bin 19966 -> 44338 bytes .../doc/installation_guide.xml | 996 ++++++++++ .../doc/introduction.xml | 298 ++- .../doc/log_collector.xml | 392 ++++ .../doc/net_config_options.xml | 740 +++++++ .../doc/troubleshooting.xml | 169 ++ .../doc/upgrade_ena.xml | 537 +++++ .../doc/vnf_mg.xml | 481 +++++ 21 files changed, 3807 insertions(+), 3259 deletions(-) delete mode 100644 doc/book-enea-nfv-access-getting-started/doc/definitions_and_acronyms.xml delete mode 100644 doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml delete mode 100644 doc/book-enea-nfv-access-getting-started/doc/getting_started_ucpe_manager.xml create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/archive_list.png create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/collect_debug_logs.png create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/debug_settings.png create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/dev_file_mg.png create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/download_files.png create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/fault_events.png create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/prep_deploy.png create mode 100755 doc/book-enea-nfv-access-getting-started/doc/images/prep_execution.png create mode 100644 doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml create mode 100644 doc/book-enea-nfv-access-getting-started/doc/log_collector.xml create mode 100644 doc/book-enea-nfv-access-getting-started/doc/net_config_options.xml create mode 100644 doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml create mode 100644 doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml create mode 100644 doc/book-enea-nfv-access-getting-started/doc/vnf_mg.xml (limited to 'doc') 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 @@ Advanced Configurations - This chapter describes possible configurations for select advanced - features such as the Hugepage Reservation Service, UEFI Secure Boot and Bare - Metal Provisioning. These features are optional in the Enea NFV Access - platform. If you do not intend to use these features, skip this - chapter. + This chapter describes possible configurations for advanced features + such as the Hugepage Reservation Service, UEFI Secure Boot and Bare Metal + Provisioning. These features are optional in the Enea NFV Access platform. + If you do not intend to use these features, skip this chapter. -
- Hugepage Reservation Service - - NFV Access implements an automatic hugepage allocation service that - is triggered at each startup. The service is skipped if hugepages have - been allocated in the kernel boot command line. - - There are two strategies outlined for hugepage allocation: +
+ Bare Metal Provisioning - - - If a system has an amount of memory up to 8GB, the allocation - algorithm will reserve up to 30% (no more than 2GB), for the OS and - the rest as 2MB hugepages. - + Bare Metal Provisioning can be used for automated deployment of the + Enea NFV Access Run Time Platform on a large number of uCPE devices. The + uCPE devices may have no previous operating system installed, or are + reinstalled without preserving any existing data. Enea NFV Access Bare + Metal Provisioning is based on standardized Pre-Boot Execution environment + (PXE) booting. - - If a system has an amount of memory that's higher than 8GB, the - allocation algorithm will reserve all but 2GB of memory as 1GB - hugepages, leaving the rest (2GB) to be used by the OS. - - + The Bare Metal Provisioning process begins by PXE booting an Enea + NFV Access installer initramfs image. The installer + downloads a configuration file, as well as the Enea NFV Access Run Time + Platform image and then proceeds to install the system by dividing the + disk into 2 partitions: a GPT partition containing the GRUB boot loader + and a second partition containing the Enea NFV Access Run Time Platform + root filesystem. When the installation is complete, the uCPE device is + automatically rebooted into Enea NFV Access Run Time Platform. - This is a best effort reservation after kernel boot, so the - results may vary accordingly. + The .hddimg, initramfs, and + bzImage files are available in the + Enea_NFV_Access_Run_Time_Platform_ + <processor>_<version>-<build_number>.tar.gz + file you downloaded with your release. -
- Customizing Automatic Hugepage Reservation - - Configuration of Hugepage reservation is done in - /etc/enea-nfv-access/hugepages.cfg. - - Parameters used by the automatic algorithm: - +
+ Prerequisites - + - hugepage_setup: Enables the automatic - configuraiton algorithm. It has only one value, - auto. For manual configuration comment or remove - this parameter. Use the other parameter descriptions as a - template/example. + The uCPE devices to be installed are connected in a working + PXE network boot environment. The PXE server can be set up using any + Linux distribution that includes TFTP and DHCP software packages. + Refer to the documentation for your distribution for setup + instructions. - threshold_to_use_1g: Decides the threshold - which instructs the algorithm to use 1GB hugepages. If a system's - memory is higher than threshold_to_use_1g, then - the algorithm will use 1GB hugepages, otherwise it will use 2MB - hugepages. + An HTTP server must be available and accessible from the uCPE + devices in the provisioning network. Note that the installer will + use the same interface that the uCPE device is PXE-booted from, to + obtain an IP address using DHCP and access the HTTP server. - percent_os_alloc: Decides how much memory - to try to reserve for userspace applications. The algorithm will try - to reserve at least the value of percent_os_alloc - of the total system memory for userspace applications. + The uCPE devices are preconfigured in BIOS to boot from the + hard drive where the Enea NFV Access Run Time Platform will be + installed. - maximum_os_alloc_mb: Maximum amount of - memory to allocate for userspace applications. If - percent_os_alloc of the total system memory - exceeds maximum_os_alloc_mb then the maximum - allocated memory for userspace applications is - maximum_os_alloc_mb. + A remote management tool is available that can be used to set + the next boot option to PXE and reboot the uCPE devices in order to + begin the installation. +
- Example of automatic Hugepage - Configuration: - - hugepage_setup = auto - threshold_to_use_1g = 8192 - percent_os_alloc = 30 - maximum_os_alloc_mb = 2048 +
+ Server Configuration - The following possible allocations can result (based on total - system memory available): + The following images provided with your Enea NFV Access release + need to be made available on the PXE and HTTP servers: - + - 2GB of memory: approximately 30% will be allocated for the OS - and the rest will be allocated as 2MB hugepages. + Copy the Enea NFV Access installer + initramfs image and kernel + bzImage for your uCPE device architecture to the + TFTP directory on the PXE server (e.g + /var/lib/tftpboot). - 4GB of memory: approximately 30% will be allocated for the OS - and the rest will be allocated as 2MB hugepages. + Compress the Enea NFV Access Run Time Platform + .hddimg image for the uCPE device architecture + using gzip and copy the resulting + hddimg.gz file to the HTTP server. + - - 16GB of memory: approximately 2GB will be allocated for the OS - and the rest as 1GB hugepages. - - +
+ Installation Configuration File - - The memory allocated for the kernel and hugepages might vary - slightly depending on how much memory is available. - -
+ An installation configuration file needs to be prepared on the + HTTP server. The format of the configuration file is a list of + "name = value" pairs and the available parameters + are described below. -
- Customizing Manual Hugepage Reservation + Mandatory parameter(s): - The automatic algorithm can be disabled and hugepages in turn, - configured manually. To do this, comment the line which defines - hugepage_setup as auto and - configure memory for each CPU socket in the following manner: + + + image_url. The HTTP server URL used for + downloading the Enea NFV Access Run Time Platform image. + + - <NUMA node>.<hugepage size> = <number of pages> + Optional parameters: - Where <NUMA node> refers to a node which - is part of the system's NUMA topology, <hugepage - size> decides what type of hugepages should be set and - <number of hugepages> is how many hugepages of - <hugepage size> should be allocated. + + + install_drive. The name of the drive + where the Enea NFV Access Run Time Platform will be installed (e.g + /dev/sda). If not set, the installer will use + the largest detected (non-USB) drive on the uCPE device. + - To list the available system nodes, run: + + prompt_user. If the parameter is set to + "yes", the installer will ask for confirmation before formatting + and partitioning the drive. The default behaviour is to proceed + automatically without any user interaction. + + - ls -d /sys/devices/system/node/node* + Installation Configuration File Example: - To list available hugepage sizes, per node, run: + image_url = http://192.168.1.100/enea-nfv-access-xeon-d.hddimg.gz +install_drive = /dev/sda - ls -d /sys/devices/system/node/node*/hugepages/hugepages-* + + The installation configuration file needs to use the Linux + end-of-line format (\n), not the Windows format (\r\n). + +
- Example of Manual Hugepage Configuration, configuring the system - to allocate three 1GB hugepages and 512 of 2MB hugepages on node: +
+ PXE Configuration - node0.2048kB = 512 -node0.1048576kB = 3 + A PXE entry for the Enea NFV Access installation needs to be + added as the default boot selection in the pxelinux configuration file + (e.g /var/lib/tftpboot/pxelinux.cfg/default). The + PXE entry should have the following settings: - - Make sure there are no hugepages reserved in the kernel boot - command line, these will override any manual configuration done in the - service. - + default nfv_access +label nfv_access +menu label ^NFV_ACCESS_INSTALLER +kernel <Path to kernel> +append root=/dev/ram0 initrd=<Path to initramfs> LABEL=pxe-installer \ + INSTALL_CFG=http://<Server IP>/<Path to install config file> \ + console=ttyS0,115200 earlyprintk=ttyS0,115200 +ipappend 2 +
+
+ +
+ Starting the Installation + + To initiate the installation, set the boot device (for next boot + only) to PXE and reboot the uCPE devices. How to do this depends on the + remote management capabilities of the uCPE devices and may require + vendor-specific tools. + + Example initiation using ipmitool: + + ipmitool -U <user> -P <password> -H <uCPE device IPMI IP address> chassis bootdev pxe +ipmitool -U <user> -P <password> -H <uCPE device IPMI IP address> power reset + + The uCPE devices should be configured in BIOS to boot from the + installation drive first in order to automatically start the Enea NFV + Access Run Time Platform when the installation is finished.
@@ -223,6 +246,11 @@ node0.1048576kB = 3 These certificates need to be manually enrolled in BIOS. The exact details on how to proceed may vary depending the version of the UEFI firmware. + + The UEFI firmware is normally shipped with factory preloaded + certificates. If these do not already include Certificates from Enea, + they will need to be appended or replaced with the Enea + Certificates.
@@ -234,173 +262,146 @@ node0.1048576kB = 3
-
- Bare Metal Provisioning +
+ Hugepage Reservation Service - Bare Metal Provisioning can be used for automated deployment of the - Enea NFV Access Run Time Platform on a large number of uCPE devices. The - uCPE devices may have no previous operating system installed, or are - reinstalled without preserving any existing data. Enea NFV Access Bare - Metal Provisioning is based on standardized Pre-Boot Execution environment - (PXE) booting. + NFV Access implements an automatic hugepage allocation service that + is triggered at each startup. The service is skipped if hugepages have + been allocated in the kernel boot command line. - The Bare Metal Provisioning process begins by PXE booting an Enea - NFV Access installer initramfs image. The installer - downloads a configuration file, as well as the Enea NFV Access Run Time - Platform image and then proceeds to install the system by dividing the - disk into 2 partitions. A GPT partition containing the GRUB boot loader - and a second partition containing the Enea NFV Access Run Time Platform - root filesystem. When the installation is complete, the uCPE device is - automatically rebooted into Enea NFV Access Run Time Platform. + There are two strategies outlined for hugepage allocation: + + + + If a system has an amount of memory up to 8GB, the allocation + algorithm will reserve up to 30% (no more than 2GB), for the OS and + the rest as 2MB hugepages. + + + + If a system has an amount of memory that's higher than 8GB, the + allocation algorithm will reserve all but 2GB of memory as 1GB + hugepages, leaving the rest (2GB) to be used by the OS. + + - The .hddimg, initramfs, and - bzImage files are available in the - Enea_NFV_Access_Run_Time_Platform_ - <processor>_<version>-<build_number>.tar.gz file you - downloaded with your release. + This is a best effort reservation after kernel boot, so the + results may vary accordingly. -
- Prerequisites +
+ Customizing Automatic Hugepage Reservation - + Configuration of Hugepage reservation is done in + /etc/enea-nfv-access/hugepages.cfg. + + Parameters used by the automatic algorithm: + + + - The uCPE devices to be installed are connected in a working - PXE network boot environment. The PXE server can be set up using any - Linux distribution that includes TFTP and DHCP software packages. - Refer to the documentation for your distribution for setup - instructions. + hugepage_setup: Enables the automatic + configuraiton algorithm. It has only one value, + auto. For manual configuration comment or remove + this parameter. Use the other parameter descriptions as a + template/example. - An HTTP server must be available and accessible from the uCPE - devices in the provisioning network. Note that the installer will - use the same interface that the uCPE device is PXE-booted from, to - obtain an IP address using DHCP and access the HTTP server. + threshold_to_use_1g: Decides the threshold + which instructs the algorithm to use 1GB hugepages. If a system's + memory is higher than threshold_to_use_1g, then + the algorithm will use 1GB hugepages, otherwise it will use 2MB + hugepages. - The uCPE devices are preconfigured in BIOS to boot from the - hard drive where the Enea NFV Access Run Time Platform will be - installed. + percent_os_alloc: Decides how much memory + to try to reserve for userspace applications. The algorithm will try + to reserve at least the value of percent_os_alloc + of the total system memory for userspace applications. - A remote management tool is available that can be used to set - the next boot option to PXE and reboot the uCPE devices in order to - begin the installation. + maximum_os_alloc_mb: Maximum amount of + memory to allocate for userspace applications. If + percent_os_alloc of the total system memory + exceeds maximum_os_alloc_mb then the maximum + allocated memory for userspace applications is + maximum_os_alloc_mb. -
-
- Server Configuration + Example of automatic Hugepage + Configuration: - The following images provided with your Enea NFV Access release - need to be made available on the PXE and HTTP servers: + hugepage_setup = auto +threshold_to_use_1g = 8192 +percent_os_alloc = 30 +maximum_os_alloc_mb = 2048 - + The following possible allocations can result (based on total + system memory available): + + - Copy the Enea NFV Access installer - initramfs image and kernel - bzImage for your uCPE device architecture to the - TFTP directory on the PXE server (e.g - /var/lib/tftpboot). + 2GB of memory: approximately 30% will be allocated for the OS + and the rest will be allocated as 2MB hugepages. - Compress the Enea NFV Access Run Time Platform - .hddimg image for the uCPE device architecture - using gzip and copy the resulting - hddimg.gz file to the HTTP server. + 4GB of memory: approximately 30% will be allocated for the OS + and the rest will be allocated as 2MB hugepages. - - -
- Installation Configuration File - - An installation configuration file needs to be prepared on the - HTTP server. The format of the configuration file is a list of - "name = value" pairs and the available parameters - are described below. - Mandatory parameters: - - - - image_url. The HTTP server URL used for - downloading the Enea NFV Access Run Time Platform image. This - image will be installed on the uCPE device(s) in the - hddimg.gz format. - - - - Optional parameters: - - - - install_drive. The name of the drive - where the Enea NFV Access Run Time Platform will be installed (e.g - /dev/sda). If not set, the installer will use - the largest detected (non-USB) drive on the uCPE device. - + + 16GB of memory: approximately 2GB will be allocated for the OS + and the rest as 1GB hugepages. + + - - prompt_user. If the parameter is set to - "yes", the installer will ask for confirmation before formatting - and partitioning the drive. The default behaviour is to proceed - automatically without any user interaction. - - + + The memory allocated for the kernel and hugepages might vary + slightly depending on how much memory is available. + +
- Installation Configuration File Example: +
+ Customizing Manual Hugepage Reservation - image_url = http://192.168.1.100/enea-nfv-access-xeon-d.hddimg.gz -install_drive = /dev/sda + The automatic algorithm can be disabled and hugepages in turn, + configured manually. To do this, comment the line which defines + hugepage_setup as auto and + configure memory for each CPU socket in the following manner: - - The installation configuration file needs to use the Linux - end-of-line format (\n), not the Windows format (\r\n). - -
+ <NUMA node>.<hugepage size> = <number of pages> -
- PXE Configuration + Where <NUMA node> refers to a node which + is part of the system's NUMA topology, <hugepage + size> decides what type of hugepages should be set and + <number of hugepages> is how many hugepages of + <hugepage size> should be allocated. - A PXE entry for the Enea NFV Access installation needs to be - added as the default boot selection in the pxelinux configuration file - (e.g /var/lib/tftpboot/pxelinux.cfg/default). The - PXE entry should have the following settings: + To list the available system nodes, run: - default nfv_access -label nfv_access -menu label ^NFV_ACCESS_INSTALLER -kernel <Path to kernel> -append root=/dev/ram0 initrd=<Path to initramfs> LABEL=pxe-installer \ - INSTALL_CFG=http://<Server IP>/<Path to install config file> \ - console=ttyS0,115200 earlyprintk=ttyS0,115200 -ipappend 2 - -
-
+ ls -d /sys/devices/system/node/node* -
- Starting the Installation + To list available hugepage sizes, per node, run: - To initiate the installation, set the boot device (for next boot - only) to PXE and reboot the uCPE devices. How to do this depends on the - remote management capabilities of the uCPE devices and may require - vendor-specific tools. + ls -d /sys/devices/system/node/node*/hugepages/hugepages-* - Example initiation using ipmitool: + Example of Manual Hugepage Configuration, configuring the system + to allocate three 1GB hugepages and 512 of 2MB hugepages on node: - ipmitool -U <user> -P <password> -H <uCPE device IPMI IP address> chassis bootdev pxe -ipmitool -U <user> -P <password> -H <uCPE device IPMI IP address> power reset + node0.2048kB = 512 +node0.1048576kB = 3 - The uCPE devices should be configured in BIOS to boot from the - installation drive first in order to automatically start the Enea NFV - Access Run Time Platform when the installation is finished. + + Make sure there are no hugepages reserved in the kernel boot + command line, these will override any manual configuration done in the + service. +
\ 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 @@ xmlns:xi="http://www.w3.org/2001/XInclude" /> - - - - - - + + + + + + + + + + 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 @@ - - - - Definitions and Acronyms - -
- Definitions - - - Definitions - - - - - - - - - Enea NFV Access - - The Enea NFV Access Run Time Platform and uCPE - Manager. - - - - Enea NFV Access Run Time Platform - - A lightweight, multi-architecture virtualization platform, - supporting Virtual Machines (KVM / QEMU). - - - - Enea uCPE Manager - - Enea Universal Customer Premises Equipment Manager. - - - - uCPE device - - A whitebox (e.g. Intel XeonD) running Enea NFV Access Run - Time platform. - - - -
-
- -
- Acronyms - - - acronyms - - - - - - - - - API - - Application Programming Interface. - - - - DPDK - - Data Plane Development Kit. - - - - EFI - - Extensible Firmware Interface. - - - - FCAPS - - Fault-management, Configuration, Accounting, Performance - and Security. - - - - NETCONF - - Network Configuration Protocol. - - - - NFV - - Network Functions Virtualization. - - - - OVS - - Open vSwitch. - - - - UEFI - - Unified Extensible Firmware Interface. - - - - SR-IOV - - Single Root Input/Output Virtualization. - - - - PCI - - Peripheral Component Interconnect. - - - - PCI Passthrough - - PCI Passthrough allows for use of a physical PCI device, - e.g. a network card inside a VM. If you "PCI passthrough" a - device, the device is not available to the host anymore. - - - - REST - - Representational State Transfer. - - - - VNF - - Virtual Network Function. - - - -
-
- 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 @@ - - - - Getting Started with Enea NFV Access - -
- Enea NFV Access Run Time Platform Installer - - The current release supports two methods of installation: - - - - Manual installation from a USB stick using the Enea NFV Access - Web-installer, which guarantees a clean installation of NFV Access on - a uCPE device. - - - - Mass installation and automated deployment using Bare Metal - Provisioning. - - - - For more information about Bare Metal Provisioning please refer to - section Bare Metal Provisioning in - Manual. - -
- Prerequisites - - To install the Enea NFV Access Run Time Platform, 3 things are - required: a USB stick (16GB or larger), a development machine with root - permissions (Linux or Windows) and a uCPE device. - - Minimal requirements for the uCPE device: - - - - EFI and virtualization support. - - - - 2 cores - - - - 4GB RAM - - - - Storage Device (SSD recommended). - - - - BIOS settings that need to be enabled: - - - - EFI - - - - Intel Virtualization Technology (VT-x) - - - - Intel Virtualization Technology for Directed I/O (VT-d) - - - - SR-IOV - - -
- -
- Installer Setup and Usage for a manual installation - - To install Enea NFV Access Run Time Platform - on a physical drive - - - - Go to the installer location: # cd <path_to_EneaNFV_Access_folder>/<architecture>/ -install/nfv-installer/script-installer - - - - Execute the installer script: # sudo ./nfv_installer.sh - - - - Optionally, press ENTER to see the list of available - commands:help - displays a guide on how to use the installer -list-params - lists all available parameters -list-steps - lists the installer steps and the parameters that they depend on -set - sets a parameter (e.g. set drive=/dev/sda) -clear - clears a parameter (e.g. clear drive) -list-partitions - lists current drives and partitions -dry - performs a simulation test run -run - executes the installer, using the values you set for each parameter -q or quit - exits the script - - - - Set the required parameters depending on what steps you want - to run: - - - When using the installer for the first time, make sure to - set ALL parameters in order to be able to run all steps. See - Example 2 for details. - - - # set <parameter_name>=<parameter_value> - - - - drive=</dev/sdaX> - sets the - drive which will be partitioned. - - - - grub_binary=<file> - points - to the GRUB executable, which will be - installed where grub_destination is - set. - - - - grub_destination=<drive> - - specifies the partition where GRUB will be - installed. - - - - rootfs_destination=<drive> - - specifies the partition where the rootfs - will be deployed, used by GRUB to boot - from. - - - - rootfs_targz=<rootfs.tar.gz - file> - sets the archive of the Enea NFV Access - rootfs you wish to unpack. The archive will - be unpacked where rootfs_destination is - set. Which type of archive file you unpack depends on whether - you are booting from an SSD/HDD or from a USB drive. - - - - - - Optionally, perform a test run before affecting the actual - layout of the physical media, with the command: dry - - - - Run the installer: run - - - - Exit the script: quit - - - - The Enea NFV Access installer creates a bootable media by - performing three steps. Each of the following 3 steps is executed or not - depending on whether certain parameters are set: - - - - Format drive. Creates a 512MB partition to be used by - GRUB, and another for use by the - rootfs. The second partition should occupy the - rest of the physical media, minus the first partition. This step - depends on setting these parameter(s): drive= - - - - GRUB install. Installs the grub_binary on - the drive set for grub_destination. A - grub.cfg file is created. This file is - configured by the user, to boot from the - rootfs_destination. This step depends on setting - these parameter(s):grub_destination= -grub_binary= -rootfs_destination= - - - - Root Filesystem install. Copies and unpacks the files found in - rootfs_targz to the - rootfs_destination. This step depends on setting - these parameter(s):rootfs_targz= -rootfs_destination= - - - - After using the installer and setting up the bootable media, - connect it to the uCPE device and configure the uCPE device to use it as - a primary boot device. -
- -
- Creating a bootable USB stick - - In order to install the Enea NFV Access Run Time Platform, you - must first create a bootable USB stick with the image you intend to - install. Follow the example below to proceed. - - - The .hddimg image is available in the - Enea_NFV_Access_Run_Time_Platform_ - <processor>_<version>-build<build_number>.tar.gz - file you downloaded with your release. - - - Create a bootable USB stick - image - - - - Copy the .hddimg image file provided by - Enea, onto a development machine. - - - - Connect the USB stick to the development machine and identify - the device name given by the system with lsblk: - NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT -sda 8:0 1 28.7G 0 disk -sdb 8:0 0 111.8G 0 disk -|-sdb1 8:1 0 111.8G 0 part - - - - Copy the .hddimg image onto the USB stick, - e.g: sudo dd if=./enea-nfv-access-<machine>.hddimg \ -of=/dev/sdb bs=4M conv=fsync - - - - Where enea-nfv-access-<machine>.hddimg - is the .hddimg file and - sdb is the assigned USB device name. -
- -
- Installing Enea NFV Access - - How to install the Enea NFV Access Run Time - Platform using a bootable USB stick image - - - - Plug the USB stick into the uCPE device. Connect a laptop - directly into one of the ports that will not later be chosen as a - WAN port. No other ports should be connected. - - - - Power up the uCPE device and boot the USB stick. Verify that - the USB stick is selected from the BIOS boot menu. - - - - Once the USB stick is properly booted, the Web-installer - application starts automatically and can be accessed in a web - browser at http://172.16.1.1 (port 80). - - On the first page of the Web-installer, the user should fill - in: - - - - The uCPE Manager IP - Address. - - - - The Device ID. The unique - identifier of the uCPE device. - - - - Customer Tags. They are - used for Zero Touch Provisining - (ZTP) and can be left empty. What can be entered here (as - needed), are the tag(s) specified when creating an offline - configuration in the uCPE Manager. - - - - On the second page of the Web-installer, the user should fill - in: - - - - The Layer 3 configuration of WAN - Interface(s). Static or Dynamic IP must be - specified. - - During network configuration, WAN cables will be plugged - into the device in order to identify ports and make them - available for configuration. Each port with a physically - connected cable will be automatically set as a WAN port and must - be configured (DHCP is the default setting). The user needs to - connect the same quantity of cables as the number of WAN ports - that he wishes to configure. No LAN ports should be connected - nor configured at this time. The configured WAN cables cannot be - removed after being configured. - - - The LAN port used to access the Web-installer from the - laptop will not be shown and cannot be configured. - - - - - The Management Interface. - The interface that will be used by the uCPE Manager to - communicate with the device. - - - - - - When the user has completed the configuration steps in the - Web-installer, NFV Access is installed on the hard drive. The - largest drive found on the device will be used for - installation. - - -
- -
- Booting NFV Access - - When the installation has finished successfully, the user should - remove the USB stick before confirming the reboot of the device in - Web-installer and ensure that BIOS is configured to boot from the hard - drive. - - When configured with the Web-installer GUI, the uCPE device - start-up sequence will configure the interfaces accordingly and try to - register the device in the uCPE manager. If connectivity is established - with the uCPE manager server and a device with a matching Device ID is - found, the configuration is successful, and the connection is - established. - - - If NFV Access was installed by Bare Metal Provisioning, the - Web-installer will launch at start-up expecting the user to provide - the post-installation configuration. The Web-installer will be - launched on port 80 for post-installation configuration: - http://172.16.1.1. - - - In case of failure, the user should remove all WAN cables, - re-attach the laptop, reboot the device and then access the - Web-installer on http://172.16.1.1. - - - To make a new connection attempt with the uCPE manager server - using the existing configuration, just reboot the uCPE device. This - can for example be useful if the uCPE device was added in the uCPE - manager after it was already started. - - - After having established a successful connection with the uCPE - Manager, the user will connect any LAN cable(s) that should be - connected to the device. - -
- -
- Examples - - Below are a few examples of setups that the Enea NFV Access - installer can be used for: - - - - Partitioning a drive: - - set drive=/dev/sda -run - - - - Partitioning a drive, installing GRUB, and a Root - Filesystem: - - set drive=/dev/sda -set grub_destination=/dev/sda1 -set grub_binary=/home/user/grub-binary.efi -set rootfs_destination=/dev/sda2 -set rootfs_targz=/home/user/rootfs.tar.gz -run - - - - Deploying ONLY a root filesystem: - - set rootfs_destination=/dev/sda2 -set rootfs_targz=/home/user/rootfs.tar.gz -run - - -
-
- -
- NFV Access Release content - - The NFV Access 1.1 Release contains along with other items, - documentation, pre-built kernels and images, a bootloader and a - SDK. - - The directories structure is detailed below: - - -- documentation/ - /* NFV Access documentation */ --- xeon-d/ - /* artifacts for the host side */ - -- deb/ - /* deb packages */ - -- images/ - -- enea-image-virtualization-host - /* precompiled artifacts for the Host release image */ - -- various artifacts - -- enea-image-virtualization-host-sdk - /* precompiled artifacts for the Host SDK image. - The SDK image contains userspace tools and kernel - configurations necessary for developing, debugging - and profiling applications and kernel modules */ - -- various artifacts - -- sdk - /* NFV Access SDK for the host */ - -- enea-glibc-x86_64-enea-image-virtualization-host-sdk / - -corei7-64-toolchain-7.0.sh - /* self-extracting archive installing - cross-compilation toolchain for the host */ --- qemux86-64 - /* artifacts for the guest side */ - -- deb/ - /* deb packages */ - -- images/ - -- enea-image-virtualization-guest - /* precompiled artifacts for the Guest image */ - -- various artifacts - -- sdk - /* NFV Access SDK for the guest */ - -- enea-glibc-x86_64-enea-image-virtualization-guest-sdk / - -core2-64-toolchain-7.0.sh - /* self-extracting archive installing cross-compilation - toolchain for the guest (QEMU x86-64) */ - - For each combination of image and uCPE device, the following set of - artifacts is available: - - -- bzImage - /* kernel image */ --- bzImage-<target>.bin - /* kernel image, same as above */ --- config-<target>.config - /* kernel configuration file */ --- core-image-minimal-initramfs-<target>.cpio.gz - /* cpio archive of the initramfs */ --- core-image-minimal-initramfs-<target>.qemuboot.conf - /* qemu config file for the initramfs image */ --- <image-name>-<target>.ext4 - /* EXT4 image of the rootfs */ --- <image-name>-<target>.hddimg - /* msdos filesystem containing syslinux, kernel, initrd and rootfs image */ --- <image-name>-<target>.iso - /* CD .iso image */ --- <image-name>-<target>.qemuboot.conf - /* qemu config file for the image */ --- <image-name>-<target>.tar.gz - /* tar archive of the image */ --- <image-name>-<target>.wic - /* Wic image */ --- microcode.cpio - /* kernel microcode data */ --- modules-<target>.tgz - /* external kernel modules */ --- ovmf.*.qcow2 - /* ovmf firmware for uefi support in qemu */ --- rmc.db - /* Central RMC Database */ --- systemd-bootx64.efi - /* systemd-boot EFI file */ --- grub-efi-bootx64.efi - /* GRUB EFI file */ -
- -
- How to use the Prebuilt Artifacts - -
- Booting Enea NFV Access using RAMDISK - - There may be use cases, especially at first target ramp-up, where - the HDD/SDD has no partitions and you need to prepare the disks for - boot. Booting from ramdisk can help with this task. - - The prerequisites needed to proceed: - - - - Enea NFV Access ext4 rootfs image - - enea-nfv-access-xeon-d.ext4.gz - - - - Enea NFV Access kernel image - bzImage - - - - BIOS has PXE boot enabled - - - - PXE/tftp server configured and connected (ethernet) to - target. - - - - Unzip enea-nfv-access-xeon-d.ext4 and copy bzImage and - enea-nfv-access-xeon-d.ext4 images to the tftpserver configured for PXE - boot. - - Use the following as an example for the PXE configuration - file: - - default vesamenu.c32 -prompt 1 -timeout 0 - -label el_ramfs - menu label ^EneaLinux_RAMfs - kernel bzImage - append root=/dev/ram0 initrd=enea-nfv-access-xeon-d.ext4 / - ramdisk_size=1200000 console=ttyS0,115200 eralyprintk=ttyS0,115200 - - Restart the target. Then enter (F11) in the Boot Menu and select - the Ethernet interface used for PXE boot. From the PXE Boot Menu select - Enea NFV Access_RAMfs. Once the Enea - NFV Access is started you can partition the HDD/SDD and install GRUB as - described in in the following section. -
- -
- Partitioning a new harddisk and installing GRUB - - The prerequisites needed: - - - - grub (grub-efi-bootx64.efi) - availalble as - a pre-built artifact under - xeon-d/images/enea-nfv-access. - - - - e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb,/ - - dosfstools_4.1-r0.0_amd64.deb - available - under xeon-d/deb. - - - - Proceed using the following steps: - - - - Boot target with Enea NFV Access from RAMDISK - - - - Install prerequisite packages: - - > dpkg -i e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb -> dpkg -i dosfstools_4.1-r0.0_amd64.deb - - - - Partition the disk: - - > fdisk /dev/sda -fdisk> g {GPT partition type} -fdisk> n -fdisk> 1 -fdisk> {default start part} -fdisk> +512M -fdisk> t -fdisk> 1 {ESP/EFI partition} -fdisk> n -fdisk> 2 -fdisk> {default start part} -fdisk> +18G -fdisk> 3 -fdisk> {default start part} -fdisk> +20G -... -fdisk> 7 -fdisk> {default start part} -fdisk> {default end end part} - -fdisk> p {print partion table} -fdisk> w {write to disk} -fdisk> q - - - - Format the partitions: - - > mkfs.fat -F32 -nEFI /dev/sda1 -> mkfs.ext4 -LROOT /dev/sda2 -> mkfs.ext4 -LROOT /dev/sda3 -> mkfs.ext4 -LROOT /dev/sda4 -> mkfs.ext4 -LROOT /dev/sda5 -> mkfs.ext4 -LROOT /dev/sda6 -> mkfs.ext4 -LROOT /dev/sda7 - - - - Create a GRUB partition: - - > mkdir /mnt/boot -> mount /dev/sda1 /mnt/boot -> mkdir -p /mnt/boot/EFI/boot - -> cp grub-efi-bootx64.efi /mnt/boot/EFI/boot/bootx64.efi -> vi /mnt/boot/EFI/boot/grub.cfg -default=1 - -menuentry "Linux Reference Image" { - linux (hd0,gpt2)/boot/bzImage root=/dev/sda2 ip=dhcp -} - -menuentry "Linux sda3" { - linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp -} - -menuentry "Linux sda4" { - linux (hd0,gpt4)/boot/bzImage root=/dev/sda4 ip=dhcp -} - -menuentry "Linux sda5" { - linux (hd0,gpt5)/boot/bzImage root=/dev/sda5 ip=dhcp -} - -menuentry "Linux sda6" { - linux (hd0,gpt6)/boot/bzImage root=/dev/sda6 ip=dhcp -} - -menuentry "Linux sda7" { - linux (hd0,gpt7)/boot/bzImage root=/dev/sda7 ip=dhcp -} - - -
- -
- Installing and booting Enea NFV Access on the harddisk - - After partitioning the harddisk, boot Enea NFV Access from RAMFS - or from a reference image installed on one of the partitions. - - To install Enea NFV Access image on a partition follow these - steps: - - - - Copy your image on target: - - server> scp ./enea-nfv-access-xeon-d.tar.gz / -root@<target_ip>:/home/root/ - - - - Extract image onto the desired partition: - - target> mount /dev/sda3 /mnt/sda -target> tar -pzxf /home/root/enea-nfv-access-xeon-d.tar.gz / --C /mnt/sda - - Alternately, you can do both steps in one command from the - server: - - server> cat ./enea-nfv-access-xeon-d.tar.gz | / -ssh root@<target_ip> "cd /mnt/sda6; tar -zxf -" - - - - Reboot - - - - From the GRUB menu select your partition - - - - - In order to change kernel boot parameters you need to mount the - GRUB partition (i.e. /dev/sda1) and change the - EFI/boot/grub.cfg file. - -
-
- \ 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 @@ - - - Getting Started with Enea uCPE Manager - -
- Prerequisites - - Listed below are the main generic prerequisites required so that the - uCPE Manager can be deployed on the host platform: - - - - A uCPE device with Enea NFV Access Run Time Platform - installed. - - - - A machine running CentOS 7 with network access to the physical - device. - - - - CPU, RAM and storage requirements for the uCPE Manager: - - - - For small-sized deployments (tens of devices): - - - - 4 cores - - - - 16 GB RAM - - - - 300 GB hard-drive - - - - - - For mid-sized deployments (hundreds of devices): - - - - 8 cores - - - - 32 GB RAM - - - - 300 GB hard-drive - - - - - - For large deployments (thousands of devices): - - - - 16 cores - - - - 64-256 GB RAM - - - - 1 - 2 TB hard-drive - - - - - - -
- -
- Install the Enea uCPE Manager - - Unpack the uCPE Manager and install it following the instructions - below. - -
- Preparing your system - - - - Install Java: - - - - Install OpenJDK 11: - - sudo yum install java-11-openjdk-devel - - - - Verify the installation: - - java -version - -openjdk version "11.0.3" 2019-04-16 LTS -OpenJDK Runtime Environment 18.9 (build 11.0.3+7-LTS) -OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing) - - - If there are multiple java versions installed, switch - between them using the following command: - - alternatives --config java - - Optionally, the user can switch between the javac versions using: - alternatives --config javac. - - - - - The following system variables need to point to the - OpenJDK 11 installation: - - export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which java))))) -export PATH=$PATH:$JAVA_HOME/bin -export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar - - - In order to make these system variables persistent, the commands given above - should be added to a script in the /etc/profile.d/ folder. - Sudo access is needed for this operation. - - - - - - - Open a terminal with administrative rights, i.e. log into a - bash shell with - root privileges. - - - - If you plan to use the PostgreSQL server bundled with the uCPE - Manager, verify that there is no existing installation of the - Postgres database. Execute the following command to check if you - have a currently running PostgreSQL database server: - - ps -ef | grep post - - To remove a currently installed PostgreSQL server (including - the existing postgres user), run the following commands: - - yum remove postgres\* -rm -f /var/lib/pgsql -rm -f /etc/postgres-reg.ini -userdel postgres - - - This step is not necessary if the uCPE Manager will be using - an external database (like MariaDB). - - - - - Choose the target installation folder, e.g. - /opt/ems. Everything will be installed under a - folder called ucpemanager within the target - installation folder. - - The application files will be installed in the - /opt/ems/ucpemanager/application folder, while the database - will be installed in the /opt/ems/ucpemanager/database folder. - - - - - If you have multiple spindles, it is recommended to let the - application run off one and the database off the other. This will - result in optimum performance. It is also recommended that the swap - disk be the same as the one used for the application. - - Assuming another spindle is used (/drive2) do - the following: - - - - Create a folder which will host the database (e.g. - emsDatabase). - - - - Create a soft-link that will point to this folder: - - ln -s /opt/ems/elementcenter/database /drive2/emsDatabase - - - - Follow the installation process as described below. - - - -
- -
- Installing the uCPE Manager - - - - Open a terminal with administrative rights, i.e. log into a - bash shell with - root privileges. - - - - cd to the folder you are installing - from. - - - - Verify that the folder you are installing from contains the - following files: - - - - README - - - - install.sh - - - - doinstall.sh - - - - configureHA.sh - - - - Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz - - - - doc/ReleaseNotes - - - - - - Run the following command: - - ./install.sh /opt/ems \ - Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz - - - - This command will: - - - - Extract the application files from the compressed install - kit. - - - - Install the bundled database (if the user specifies an - internal database). - - - - Install ucpemanager as a service with the - name ucpemanager. - - - - Start the ucpemanager service. - - - - - The service will be automatically started when the computer - boots up. The user may enable the firewall in order to allow access to - these specific ports: 80 (TCP), 443 (TCP), 54327 (UDP), 5701:5708 - (TCP) and 7000:7009 (TCP). If callhome is used, access to the - following ports must also be allowed: 4334 (TCP) and 2021:2040 (TCP). - Otherwise, the user should check that the CentOS machine where the - uCPE Manager is installed has the firewall disabled. - - - Verify that the installation has succeeded by: - - - - Pointing your browser to the server machine running the uCPE - Manager. - - - - In the login screen, log in with the username: admin and password: admin. - - - - In order to manage the ucpemanager service, user can run: - service ucpemanager start/stop -
- -
- Installing with the restore option - - It is possible to use a restore file created by the "System - Backup" utility provided in the uCPE Manager, to install a system and - set it to a known state. - - - The file to be used is the zip file created by System Backup, - not the one created by the uninstall or upgrade processes described - below. - - - The name format of this file will be: - SystemBackup_MMMDD_YYYY_HHMM_SS.zip (e.g - SystemBackup_Feb19_2013_2257_42.zip). - - Follow the steps for Installation provided above and provide an - additional argument as shown below: - - ./install.sh \ - /opt/ems Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz \ - SystemBackup_MMMDD_YYYY_HHMM_SS.zip - - The other steps are exactly the same as specified in the - Installation instructions. -
- -
- Upgrading the uCPE Manager - - - - Verify that the folder you are upgrading from contains the - following files: - - - - upgrade.sh - - - - doupgrade.sh - - - - configureHA.sh - - - - Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz - - - - - - Run the following command: - - ./upgrade.sh /opt/ems \ - Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz - - - - Running this command will: - - - - Stop the currently running ucpemanager service. - - - - Create a compressed file of the ucpemanager application - folder, called: - ucpemanager-Backup-YYYYddMMHHmm.tar.gz, which - contains a snapshot of the existing installation. - - - - Rename the application folder to - application_original. - - - - Extract the application files from the specified compressed - install kit. There will now exist a (new) application folder, with - the contents of the new kit. - - - - Start the ucpemanager service. - - - - When the ucpemanager service starts, it will recognize the fact - that an old version of the application needs to be upgraded (based upon - the existence of the application_original folder. All - the relevant data from the old installation will be copied to the new - one and the application_original folder will be - deleted. -
- -
- Uninstalling an existing uCPE Manager installation - - - - Verify that the folder you are uninstalling from contains the - following files: - - - - uninstall.sh - - - - douninstall.sh - - - - - - Run the following command: - - ./uninstall.sh /opt/ems - - - - Running this command will: - - - - Stop the currently running ucpemanager service. - - - - Create a compressed file of the ucpemanager application - folder, called - ucpemanager-Backup-YYYYddMMHHmm.tar.gz, which - contains a snapshot of the existing installation. - - - - Uninstall the ucpemanager service, so that it will not startup - on reboot. - - - - Uninstall the database service (if an internal database is - being used). - - - - Completely remove the contents of the - application and database - folders. - - - - After these steps, the uCPE Manager is completely removed from the - system. -
- -
- Restoring a previous uCPE Manager installation - - - - Verify that the folder you are restoring from contains the - following files: - - - - restore.sh - - - - dorestore.sh - - - - configureHA.sh - - - - ucpemanager-Backup-YYYYddMMHHmm.tar.gz - (the original installation snapshot, as obtained from a previous - uninstall). - - - - - - Run the following command: - - ./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz - - - - Running this command will remove any vestiges of the existing - ucpemanager service, if they exist, and reinstall the ucpemanager - application on the specified target, restoring the data in the database - and files in the process. - - The ucpemanager service is then started and the older version is - now running on the system. -
-
- -
- Device Configuration and Provisioning - - The following describes the steps required for setting up the - virtualization infrastructure, ensuring that a uCPE device is ready for - virtualized service deployment. The sections herein contain information - about enrolling uCPE devices into the Enea uCPE Manager, selecting - physical interfaces to be used by virtualized networking and creating - different types of bridges to enable VNF communication. The Zero Touch - Provisioning mechanism is also touched upon, as alternative to manual - configuration of the virtualization infrastructure. - -
- Add a uCPE device to the Management System - - Enrolling uCPE devices into the Enea uCPE Manager can be - accomplished using one of the two possible methods. - -
- Direct Connection - - When using this mechanism, the uCPE Manager will periodically - poll the uCPE device, using a specified IP address as the destination, - attempting to establish a management connection. - - Add the uCPE device running the NFV Access Run Time Platform to - the management system by: - - - - Selecting in the uCPE Manager: Devices -> Manage - -> Add. - - - - Suppling information about the uCPE device, and setting the - parameters that will be used to connect to it. - - - - The relevant parameters are: - - - - Type. The type of device to be added, i.e Enea - universal CPE. - - - - Name. The name by which the device is referred to in the - uCPE Manager. - - - - SSH Port. The NETCONF Port used for communications. Default - is set to 830. - - - - SSH User Name. The user name for SSH connectivity. Default - user is root. - - - - SSH Password. Leave this blank. - - - - Device Calls Home. This checkbox indicates the direction of - device communications. For Direct Connection, leave this flag - unchecked. - - - - Device ID. The unique identifier of the uCPE device. - - -
- -
- Device Call Home Connection - - Follow the same steps as described in the previous section, - making sure that the Device Calls Home checkbox is - selected this time. - - When using this mechanism, the device will initiate a connection - to the uCPE Manager for NETCONF traffic (over SSH), while the uCPE - Manager waits for a device connection. For more information please see - section Creating a bootable USB stick in the - - Manual for more details. -
-
- -
- Configure NFV Infrastructure - - Once a management connection with the uCPE device has been - established by using any of the supported methods, the virtualization - networking infrastructure can be configured either manually or by using - Zero Touch Provisioning. - - Available network interfaces can be added to the management - system, for use by the networking virtualization infrastructure. - - In order to make physical network interfaces available to the - virtualization infrastructure and VNFs, they must be configured into the - management system. - - To add an interface into the uCPE Manager, select the uCPE device, - then from the top toolbar select Configuration -> External - Interfaces -> Configuration -> Add. The available - Interface types are detailed below. - -
- DPDK Interface Type - - Configuring a physical interface in DPDK mode will require a - DPDK-based application (e.g. OVS-DPDK) in order to access and use the - interface. An interface set as DPDK can be attached to an OVS-DPDK - bridge. - - - Make sure the Enable DPDK checkbox is - selected in Device -> Configuration -> - DPDK, otherwise no interface can be assigned as - DPDK. - - - To add a DPDK interface under the management system, set - appropriate values for the following fields: - - - - Source: name of the physical interface. - - - - Type: dpdk - - - - Networking-type: dpdk - - - - Dpdk-type: the kernel module that allows user space access - to the physical interface. Either the vfio-pci - or the igb_uio driver can be used. - - -
- -
- SR-IOV Interface Type - - SR-IOV technology allows for the creation of a number of virtual - functions on the host interface, which can be used by VNFs running on - the uCPE device. - - For SR-IOV mode configuration, the user must set values for the - following fields: - - - - Source: name of the physical interface. - - - - Type: sr-iov - - - - Networking-type: srIov - - - - sriov-mode: adapter-pool - - - - sriov-num-vfs: the number of virtual functions to - create. - - -
- -
- Standard Interface Type - - Some of the physical network interfaces available on a uCPE - device, including Ethernet interfaces, do not have DPDK or SR-IOV - support. Instead, the Linux kernel driver has to be used. Wi-Fi and - 4G/LTE modems can also be configured and used for virtualization - infrastructure and VNFs. - - To add Standard interfaces under the management system, the user - must set values for the following fields: - - - - Source: the name of physical interface. - - - - Networking-type: standard - - -
- -
- PCI Passthrough Interface Type - - For the PCI Passthrough a user does not have to configure a - physical interface, instead simply select the PCI address and connect - it to a virtual port when the VNF instantiation step is - reached. -
- -
- Manual Configuration - - For Manual Configuration of uCPE networking, select the uCPE - device first and then Configuration -> - External Interfaces, where one can find a list of - available network interfaces and their capabilities. - -
- Configuring Interfaces - - After networking interfaces have been added to the uCPE - Manager, the user can change the interface type (DPDK, SR-IOV, - Standard, WAN). - - - WAN interfaces, which are configured during the installation - of the device, do not need to be added, they will be automatically - listed as such in the uCPE manager when the device - connects. - - -
- Configuration of External Interfaces - - - - - - -
- - How to Edit the Configuration of an - Interface - - - - To edit an interface configuration type from the uCPE - Manager, select the uCPE device, then from the top toolbar - select the Configuration menu then - External Interfaces -> Configuration. The - already configured interfaces are displayed here, as can be seen - in the figure above. - - - - In order to edit an already configured interface, (as in - the example popup shown below, a WAN interface) double click on - the desired one and a popup will appear. A different popup - appears for each type of interface. From the Host Interface - window, a user can change the networking type and the IP address - assignment: - -
- Editing an Interface - - - - - - -
- - - - - The IP address assignment of an interface can be set as - static or dynamic for each type of interface. - -
- -
- Configuring Bridges - - After networking interfaces have been added to the uCPE - Manager, the user can create the necessary OVS bridges. - -
- OVS Bridges - - - - - - -
- - How to add OVS bridges in the uCPE - Manager - - - - Select the uCPE device. - - - - Select Configuration. - - - - Click OpenvSwitch. - - - - Select the Bridges option, then click Add. - - - - - Depending on the settings in Configuration -> - OpenVSwitch -> DPDK, OVS bridges with or without DPDK - support will be used on the uCPE device. - - - There are three types of bridges which can be created, each - one fulfiling a different role. - -
- uCPE In-band Management bridge - - In-band Management refers to a model where both the data - plane and control plane flow over the same network path. In some - situations (e.g. the uCPE device has only one routable IP - address), this is the only option available to both control and - configure the uCPE device, while also allowing for data-path - traffic to pass over the same physical interface. - - The solution provided by Enea for in-band management is - based upon an OpenvSwitch bridge fielding all traffic passing - through the WAN physical port. Any standard or DPDK-assigned - network interface can be used for the In-Band management - bridge. - - - The In-Band Management bridge must be recreated each time - the uCPE Manager IP address is changed. - - - To create the In-Band Management bridge, the user must set - values for the following fields: - - - - name: name of the bridge. - - - - ovs-bridge-type: inbandMgmt - - - - - The first VNF instantiated on the uCPE device must be - connected to the In-Band Management bridge and its WAN interface - must be configured as the DHCP client. - -
- -
- In-band Management bridge for VNFs - - If VNF management can be done over a dedicated virtual - interface, its possible to extend the networking infrastructure - configuration to also access the VNF's management interface over - the WAN port. - - For this setup, three types of traffic will pass over the - WAN physical interface: - - - - Device management. Part of the device configuration done - by the uCPE Manager. - - - - VNF(s) management. Enabling or disabling features of a - VNF. E.g. enabling/disabling the firewall or VPN setup. - - - - Data-path. All other traffic that is not used in the - control plane and needs to reach a LAN network. - - - - To create a VNF In-Band Management bridge, the user must set - values for the following fields: - - - - name: name of the bridge. - - - - ovs-bridge-type: vnfMgmt - - - - vnf-mgmt-address: select IPv4 as the type and fill in - the IP address for management network, e.g 10.0.0.1. - - - - - VNF management interfaces must be configured in same - network as the vnf-mgmt-address of the - bridge. For more information, please see section VNF Management in the - Manual. - -
- -
- Data-plane Bridge - - Data-plane bridges are generic bridges used for the VNF - data-plane. There are two supported sub-types: - - - - communication: allows for VNF communication towards - LAN/WAN networks. This bridge type has at least one physical - port attached to it. - - - - integration: allows for VNF-to-VNF communication - (usually for service function chaining). This bridge type does - not have any physical port attached. - - - - To create a Data-plane bridge, the user must set values for - the following fields: - - - - name: name of the bridge. - - - - ovs-bridge-type: select communication - or integration, depending on intended - usage. For communication bridges, physical interfaces can be - added to the bridge. - - -
-
-
- -
- Zero Touch Provisioning - - Zero-Touch Provisioning (ZTP) refers to the process of when a - device starts up for the first time and its initial configuration is - pushed down by an external management system, so that it is setup for - proper operation without additional manual intervention by an - operator. ZTP is an alternative to Manual configuration. - - A variety of operations can occur as part of ZTP such as initial - device setup, configuration of managed objects, etc. The goal is to - set up a device to the maximum possible extent without forcing an - operator to be physically present (initially) to manage the - device. - - An offline configuration is usually prepared in advance for the - uCPE Manager to setup the virtualization infrastructure on the uCPE - device, as soon as a device enrolls into the management system. - -
- Offline Configuration - - The Offline Configuration subsystem is used to pre-populate a - configuration for a device that will be brought under management at - a future point in time. When creating an offline configuration store - a Device ID can be specified. This ID uniquely - identifies the device to be initialized. - - Alternatively, a wildcard can be used in the Device - ID field, which results in a configuration being pushed on - all uCPE devices upon their initial connection towards the uCPE - Manager. - - To create an offline configuration, from the top toolbar menu - select Applications -> Offline - Config -> Add. The following fields - are available: - - - - Name: name of the device. - - - - Device type: Enea universal CPE. - - - - Device version: 2.2.2 - - - - Config Set: uCPE Config - - - - Device ID: device ID or a wildcard(*). - - - - Device Grouping Tags: a tag to group devices. These tags - match the customer tags provided during the installation of the - device. - - - - When a device connects to the uCPE Manager for the first time, - it checks the device to see if it has been Zero Touch Provisioned - (ZTP). If not, it looks for an offline configuration that matches - these values, in the following order: - - - - The Device ID. - - - - The set of tags. - - - - A "*" for Device ID (wildcard). - - - - If a match is found, the offline configuration is sent to the - device as part of Zero-Touch-Provisioning. - - After creating the Offline Config Store, access the device - through Applications -> offline - config -> Config App and provision - it with the required initial configuration. This operation mirrors - what happens during manual configuration described in the previous - section. -
-
- -
- Custom Scripts - - The custom scripts feature allows users to execute user-defined - scripts on the uCPE device at various times.This allows for more - flexible and advanced configurations such as a LTE modem - configuration, advanced network configurations or OVS flow rule - programming at any time. - -
- Uploading Scripts - - The scripts need to be uploaded to the uCPE Manager prior to - use. When uploading scripts to the uCPE Manager make sure to select - the right script type. - - The following script types are supported: - - - - Once-before-startup. This script will - only execute once during the startup. - - - - Always-before-startup. This script will - always execute during the startup. - - - - Once-after-startup. This script will - only execute once after the system has been started. - - - - Always-after-startup. This script will - always execute after the system has been started. - - - - Follow the instruction below to upload scripts: - - - - Select Devices -> Custom - Scripts -> Configure. - - - - Select Upload to EMS. - - - - In the Script Type menu, select the - type the uploaded script should have. - - - - Press Choose File to select the scripts - needed, and then press Send. - - -
- -
- Removing Scripts - - Follow the instruction below to remove scripts: - - - - Select Devices -> Custom - Scripts -> Configure. - - - - Select the script you want to delete from the - Uploaded Scripts tab and then click - Delete, which will remove the script - immediately from the uCPE Manager. - - -
- -
- Configuring Script Location - - The location where the scripts are staged in the uCPE Manager - can be chanaged as described below: - - - - Select Devices -> Custom - Scripts -> Configure. - - - - Select the Configuration tab and - specify a new loacation to store the scripts. - - - Change the script storage location only if you have many - scripts which you would prefer to store on another partition, - otherwise leave this configuration as is. - - - -
- -
- Running the Scripts - - How to run Custom - Scripts - - - - Select Devices -> Custom - Scripts -> Apply Scripts. - - - - In the Script Config Screen pop up, - select the devices from the device(s) chooser list on which to - run the scripts. Press the > button to - move the devices to the right side of the chooser, which is the - list of devices that will execute the selected scripts. - - - - Select the scripts from the list under the device(s) - chooser by pressing the + button. - - - - In the pop-up window, select the scripts from the list. If - there are no scripts to select, then there is no script uploaded - with that particular type. Upload the script(s) needed and try - again. - - - - Check the checkbox Reboot devices if - you want to reboot and execute the scripts at once and then - press ok. - - - The status of execution for the scripts can be seen by - opening the Fault -> - Events screen and filtering by device - and/or the event name Custom. - - - -
-
-
-
- -
- Device Upgrade - -
- Device Upgrade Process - - Device Upgrade/Install performs the following operations to the - device: - - - - Prepare for upgrade. This - stage tells the device that an upgrade is about to happen. - - - - Install file on device. This - stage copies the file to the uCPE device. - - - - Upgrade Device. This stage - causes the device to replace its running image with the newly copied - image. - - -
- -
- Managing the Device Upgrade - - Before an install or upgrade can be completed, certain - configuration data must be set. Files also need to be uploaded to the - Device Upgrade image repository in order to be uploaded to the - device. - - Launch the Device Upgrade management console by selecting - Devices -> Upgrade from the top - toolbar. The console when launched will contain the following - tabs: - - - - Image Library. To add/delete an - image. - - - - Upgrade Operations. See running upgrades, - cancel any upgrades in progress, start a device upgrade. - - - - Configuration. Upgrade configuration - parameters. - - - - Press Close when the message File - Uploaded Successfully appears on the File Upload - Screen. - - - The image file of type rootfs.ostree.tar.bz2 - is available in the - Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz - file you downloaded with your release. - - -
- Image Library - - Add an image to the image - repository/library - - - - Select Devices -> - Upgrade. - - - - Select Add from the Image - Library tab to add a new image file. - - - - Click on Choose File to provide the path - to the image file (must be of type - rootfs.ostree.tar.bz2). Select the target - hardware platform corresponding to the image being uploaded - (xeon-d or atom-c3000). - - - - Click Send to upload the image to the - image repository. - - - - Delete an image from the image - repository - - - - Select Devices -> - Upgrade. - - - - Select the image you want to delete from the Image - Library tab and then click - Delete. - - -
- -
- Upgrade Operations - - The Upgrade Operations tab allows a user to manage device - upgrades in the system. It allows the user to see all the upgrades - that are currently in progress, as well as listing the completed ones. - If an upgrade succeeds or fails, then a row will be added to the - completed upgrades table. If one fails, the failure message will be - visible here. - - - The list of completed upgrade tasks resides in memory and will - not persist across reboots of the server. - - - How to Install/Upgrade immediately or - schedule for later - - - - Select Devices -> - Upgrade. - - - - Select Upgrade Devices from the - Upgrade Operations tab. This will launch a - Multi Device Install Image screen that will - allow the user to install and upgrade more than one device at a - time or upgrade later. - - The configurable parameters are: - - - - Scheduling. Click this checkbox if - the upgrade will be done later. Schedule the day, hour and - minute for when to run the upgrade. - - - The hour represents the local uCPE Manager server - hour. - - - - - Description. An optional description - of the operation. It is recommended to add a description so - that different upgrades happening simultaneously can be - distinguished. - - - - Image File. Click on Choose - Image File to select the image file. - - - - Devices. The list of available - devices is populated when an image file is chosen. The - device(s) chooser is then populated with the list of devices - that can accept that file. Press the > - button to move the devices to the right side of the chooser, - which is the list of devices that will be upgraded. - - - - Upgrade Operation. Available options - are: - - - - Install and Activate. This will - do an image installation as well as an upgrade. - - - - Install Only. This will do an - image installation only. The image is copied to the - device, and an upgrade will be done later either at a - scheduled time or when the option Activate - Only is selected. - - - - Activate Only. This will activate - an already installed image on the device. - - - - - - - - - When the device activates the upgrade, it will be rebooted - automatically. - -
- -
- Releases installed on a Device - - The installed releases on a device can be viewed by selecting - the device first, then from the top toolbar selecting - Configuration -> Upgrade. The - installed releases on the device, the release status, release state, - commit-id and release version will be listed in a table. -
- -
- Device Status - - The status of the installation and upgrade can be viewed in the - Upgrade Operations tab. Ongoing or scheduled - upgrade operations can be viewed or cancelled. - - To view the status of an installation or - upgrade operations - - - - Select Devices -> - Upgrade. - - - - Select Upgrade Operations. The ongoing - operations are listed at the top and a history of failed or - successful operations are listed at the bottom. - - - - Select an Active or Completed - Upgrade Operation and click the Device - Status button to see detailed information regarding the - upgrade operation, including the devices involved and information - per device. - - - - To cancel an upgrade - operation - - - - Select Devices -> Upgrade - -> Upgrade Operations. - - - - Select an operation from the list and press Cancel - Upgrade and Confirm. The operation - will then be deleted from the list. - - -
- -
- Configuration - - - The default values present in the configuration of each device - are recommended for use. Modifying them is for an Advanced User - only. - - - How to Configure the uCPE device Upgrade - - - - - Select Devices -> - Upgrade. - - - - Select Configuration. - - - - The configurable parameters are: - - - - deviceImageDir. This is the disk - location of the device image repository. If an absolute path - name such as /usr/local/deviceimage is - given, then the absolute path name is used. If no absolute - pathname is given it is considered to be relative to the - installation directory. - - - - maxThreads. This number dictates how - many upgrades the system can manage at one time, either - individually launched or launched from the multi-device - screens. This value defaults to 20, which means that 20 - devices may be updated at one time. - - - - KeepAlive. This number represents the - number of seconds that a thread will be kept alive before it - is collected. If multiple installations are occurring, this - will keep the thread alive for X seconds before it is - released. If not released, it can be used by the internal - scheduling system as soon as it has completed an - upgrade. - - - - -
- - -
-
- -
- VNF Management - - The Enea uCPE Manager is responsible for onboarding, configuring - (e.g. CloudInit) and ensuring life cycle management of VNFs that are - instantiated and run on the various uCPE devices. - -
- Onboarding a VNF - - The onboarding of a VNF means adding it to the Enea uCPE Manager - VNF Catalog and preparing it for instantiation (deployment on connected - uCPE devices). This is accomplished using the Enea uCPE Manager - Onboarding graphical user interface. - - Typically, the Getting Started Guide of a VNF contains all - necessary information needed to onboard a VNF. - -
- Retrieving Artifacts - - The user must first retrieve the necessary artifacts from the - VNF vendor: - - - - Download the VNF from the commercial vendor. - - - - Procure any VNF-specific files from the VNF vendor, e.g. - license file. - - - There are no standard ways of managing VNF licenses, - therefore no general guidelines can be provided. One example of - license handling that can be employed in the uCPE Manager is the - adding of a license during the Cloud-Init setup. - - - - - Optionally, get access to the VNF specific VNF Manager for - day 1 and 2 configuration (in cloud or for local - deployment). - - - - Procure the Getting Started Guide from the VNF vendor, - preferably for KVM deployment for VNF specific configuration - information. - - -
- -
- Preparation - - Once all needed downloadables, documentation and more have been - attained, preparation for onboarding must be completed: - - - - Determine the use-case and performance requirements of the - VNF you wish to deploy: - - - - This decides what resources the VNF is configured for, - along with networking and day zero configurations. - - - Generally, the Getting Started Guide for the VNF - provides guidelines for resource allocation, but since - performance is dependent on hardware capacity, the right - resource allocation for deployment is determined through - benchmarking. - - - - - Determine the amount of hardware resources needed for - the VNF (RAM, number of CPUs and storage size). - - - - Determine how many Virtual Network Interfaces the VNF - will use. - - - - - - Determine the Day-0 configuration method from the VNF - Getting Started guidelines. - - - For many VNFs, day zero configuration can be skipped in - early onboarding efforts when automation is not of - importance. - - - - - Determine any requirements needed by the Cloud-Init file - structure and the content needed when this structure is - used. - - -
- -
- Onboarding into the uCPE Manager - - How to onboard a VNF into the uCPE Manager - - - - - Select from the top toolbar VNF -> - Descriptors - - - - Click the On-board button. - - - - When prompted by the UI, make sure the VM - Image radio button at the top of the onboarding screen - is selected, it will trigger a popup menu window. - - - - This window contains data fields where both necessary and - optional information about the VNF can be supplied. After doing so, - press the Onboard button, the uCPE Manager will create the VNF - descriptor and add it to its VNF Catalog. - -
- Onboard a VNF - - - - - - -
- - Main fields - - - - VM Image File. This is the - Virtual Machine image file for the VNF. Typically, it is a QCOW - image. Press Choose File and select the image - you wish to upload. - - - - Image Format. Select the - format which matches the image file format. - - - - VNF Type Name. This is the - name that will be used to identify this VNF. It will be shown in - the VNFs list. - - - - Description. This field - contains any description provided and is only displayed in the GUI - tables in the uCPE Manager. - - - - Version. This is the - version of the current VNF that you are hosting. It's used to - distinguish this VNF from other versions of the same type. - - - - Memory in MB. This is the - amount of memory (in megabytes) that will be provided to this type - of VNF when it is instantiated. To determine the value for this - field, consult the VNF vendor. - - - - Num of CPUs. The number of - CPUs that will be dedicated to an instance of this VNF when - created. To determine the value for this field, consult the VNF - vendor. - - - - Storage in GB. How much - disk space to provide an instance of this VNF. To determine the - value for this field, consult the VNF vendor. - - - - Interfaces Tab - - Click on the Interfaces tab to show the - Interfaces table. - - This table will contain the interfaces required by this VNF to - be configured, when creating an instance. Consult the VNF vendor to - determine which and how many are required. Each interface requires a - name, and optionally a description, used only by the uCPE - Manager. - - - CAUTION: The user MUST conserve the same order for the virtual - interfaces during both onboarding and instantiation phases. - - - Cloud Init Tab - - Click the Clout Init tab to provide the - Clout-Init configuration. There are three fields that need to be - populated: - - - - Cloud-Init - Datasource - - To onboard a VNF you must specify the Cloud-Init - Datasource that the VNF uses. This information is - procured from the VNF Vendor. Choose one of the following methods - to specify the datasource: - - - - None. If there is no - datasource. - - - - ConfigDrive. This - method allows you to provide any number of content-data files - containing Cloud-Init data. - - - - NoCloud. This is a - simpler method that uses only one cloud init file - (User-Data). - - - - ISO. Pre-cooked - cloud-init image. This image must be created by the user - according to VNF requirements. - - - - - - Cloud-Init Disk Type - - The Cloud-Init Disk Type field must be - set to either Disk, or - CD-ROM, depending on what the VNF requires. You - can get this information from the VNF Vendor. - - - - Content Files Table - - The Content Files Table is ONLY used if - you choose ConfigDrive as the Cloud-Init - Datasource. For each content file added, you must provide a - Path. When a user uses the uCPE Manager to - create an instance for multiple VNFs, they will be prompted to - provide a data file for each entry in this table. Each type of VNF - will require different cloud-init files, e.g.: a license file. The - data files will be added to the cloud-init image that the user - provides at the instantiation of the VNF. If the cloud-init image - is not provided, no Cloud-Init Data Source will be created for - that VNF and there will be no warning. - - - - Consult with the VNF vendor to determine what is required for - the VNF you are onboarding. - - Properties Tab - - In this table, you can enter values for properties that will be - used during instantiation of the VNF. The values will augment the - default values in the Domain.XML file used by - libvirt/virsh (running in NFV Access) when creating - an instance of the VNF. Consult with the VNF Vendor or ENEA support - for values needed by specific VNFs. - - Property Values - - - - numHugePages defines the number of huge - memory pages the VNF uses (for DPDK). - - - - vnfMgmtIpAddress: the IP address of the - VNF's management interface, connected to a - vnfMgmt bridge (e.g. 10.0.0.2). - - - - internalMgmtPort: the VNF's TCP/UDP port - used for management (e.g. 443). - - - - externalMgmtPort: the Management port - used for external access (e.g. 60001). - - - - - The last three properties are useful in conjuction with the - vnfMgmt bridge type. They allow the user to map - the internal VNF management port to an external port, useful for VNF - configuration from WAN. - - In the previous example, the internal TCP port 443 (HTTPS) was - mapped to the external port 60001, which allows the user to access - the VNF management port from a web browser e.g. - https://<WAN_IP>:60001. - -
-
- -
- Instantiating a VNF - - When a VNF is onboarded and available in the VNF catalog, it can - be instantiated on connected uCPE devices. The configurations provided - when the VNF is onboarded, serve as a template for instantiation. Before - instantiating any VNF, please make sure the available storage space on - the uCPE device is big enough to accommodate the VNF you need to - instantiate. - - Follow the instructions below to instantiate a VNF: - - - - Select from the top toolbar VNF -> - Instances - - - - Click the Add button. - - - - Fill out the following mandatory fields: - - - - Name: a descriptive name. - - - - VNF Type: a list of onboarded VNFs. - - - - uCPE Device: the uCPE device to instantiate the VNF - on. - - - - Networking Configuration: - - - - Connect each configured NIC with a bridge, SR-IOV or - PCI Passthrough. - - - - Set up each NIC with a driver method. - - - - - All configured NICs must be set up before instantiating - a VNF. Failure to do so will end in a failed - instantiation. - - - - - - - Add VNF-specific configuration data by uploading a Cloud-Init - file (when the Cloud-Init is used). - - - - Add any VNF-specific files (e.g license files). - - - - Hit the Create button to deploy the VNF and - run it on the specified uCPE device. - - - - Selecting the VNF -> Events menu will show - that the VNF was created and a connection was established. -
- -
- Accessing the VNF console - - Once the VNF is deployed, the VNF console can be entered using SSH - and virsh commands. The VNF Console is a typical starting point for - determining a successful deployment and configuring a VNF beyond Day - Zero. - - - - SSH to the uCPE device from the Enea uCPE Manager - (Device->SSH) using: - - - - For normal connections: the Username - (default: root), the Password (default: no - password), the Port (default: 22) and the - Reverse ssh checkbox: unchecked. - - - - For reverse ssh connections: the - Username (default: root) and the - Reverse ssh checkbox checked. The port will - be automatically choosen by the uCPE Manager in the range - defined in the System -> Configuration -> Reverse - SSH configuration panel. By default, the start port - will be 7000 and the maximum number of ports - allocated to all devices is 10. Only one port per device is - allowed. - - A SSH Tunnel between the uCPE Manager and the device will be created: - ssh -f -N -T -R < Port > :localhost:22 <uCPE Mgr user>@<uCPE MgrIP> - The device must be connected to the uCPE Manager for the tunnel to be created. - On connection, a normal ssh connection will be made: - ssh -p <Port> <Username>@localhost - - - - - - - - In SSH: - - - - Use the virsh list command to list all - running VNFs and to determine the VNF's instance number. - - - - Use the virsh console <instance - number> command to enter the VNF-specific - console. - - - - -
-
- \ 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/archive_list.png 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/collect_debug_logs.png 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/debug_settings.png 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/dev_file_mg.png 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/download_files.png 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/fault_events.png 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/prep_deploy.png 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 Binary files /dev/null and b/doc/book-enea-nfv-access-getting-started/doc/images/prep_execution.png 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 Binary files a/doc/book-enea-nfv-access-getting-started/doc/images/vnf_space.png and b/doc/book-enea-nfv-access-getting-started/doc/images/vnf_space.png 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 @@ + + + Setting up and Installing the NFV Access Base Configuration + + The setup and installation steps detailed below will deploy a base + configuration which will be used as a reference for more complex deployment + scenarios. + +
+ Hardware requirements + + The following hardware is needed for deploying the base + configuration: + + + + One CentOS 7 server + + Minimal Requirement: 4 Cores, 16 GB RAM and 300 GB single disk + storage. Make sure the CentOS 7 server is updated to the latest + revision before installing Enea NFV Access. + + The purpose of the CentOS 7 server is to host the uCPE Manager. + Network access between the CentOS 7 server and the uCPE devices is + required. The uCPE Manager and the uCPE devices will be connected on + separate subnets to avoid inconsistencies. + + + + A laptop. + + The laptop is used for 2 scenarios: + + + + Installing the NFV Access Run Time Platform on uCPE + Devices. + + + + Connecting to the Web UI of the uCPE Manager for management + and configuration. Network access between the CentOS 7 server and + the laptop is required. Please see the manual + available with your release, for recommended browsers. + + + + + + One or more uCPE devices. + + White Box devices where the Enea NFV Access Runtime Platform + will be installed, containing a minimum of 2 cores and 4 GB RAM and at + least two ethernet ports that will be configured as WAN and LAN during + deployment. + + When hosting an entire solution including one or several network + services, the hardware must also have the resources to host one or + more VNFs. During a typical evaluation, a dual VNF service on the Enea + NFV Access Run Time Platform needs a CPU with 4-8 cores and at least 8 + GB RAM. The supported Intel CPUs of Enea NFV Access are documented in + the + manual. + + Enea NFV Access needs EFI support in BIOS to boot. When + configuring the uCPE device BIOS a serial connection is + required. + + + + A 16 GB USB stick used for the uCPE Device Installation. + + +
+ +
+ Software Configuration + + The CentOS 7 machine requires a specific configuration for the setup + to work. + +
+ Firewall Configuration + + Any firewall running on the CentOS 7 server may block the + management protocols required to communicate between the uCPE device and + the uCPE Manager as well as between the uCPE Manager and its northbound + clients. Quick handling of a blocking firewall would be to disable it, + typical for a lab environment, through: + + sudo service firewalld stop + + For an advanced firewall configuration, the following ports need + to be opened: + + + Ports to be Activated + + + + + + + 80 + + TCP + + Required for WEB UI Access. + + + + 443 + + TCP + + Required for WEB UI Access and Device + Connectivity. + + + + 54327 + + UDP + + TBD.This needs to be updated + + + + 5701:5708 + + TCP + + Required for the uCPE Manager Redundancy + Protocol. + + + + 4334 + + TCP + + Required for Call Home. + + + + 2021:2040 + + TCP + + Required for Call Home. + + + + 7000:7010 + + TCP + + Required for Reverse SSH. + + + +
+ + Use the following command sequence to enable the required ports + for deployment of the uCPE Manager: + + sudo firewall-cmd --permanent --add-service=80/tcp +sudo firewall-cmd --permanent --add-service=443/tcp +sudo firewall-cmd --permanent --add-service=54327/udp +sudo firewall-cmd -permanent -add-service=5701-5708/tcp +sudo firewall-cmd --permanent --add-service=4334/tcp +sudo firewall-cmd -permanent -add-service=2021-2040/tcp +sudo firewall-cmd -reload +
+ +
+ Configuring OpenJDK and PostgreSQL + + The uCPE Manager requires a specific Java version (OpenJDK 11) and + a PostgreSQL version to operate correctly. + + Installing OpenJDK + + + + Install OpenJDK 11 using the root account: + + yum install java-11-openjdk-devel + + + + Verify the installation: + + java -version +openjdk version "11.0.3" 2019-04-16 LTS +OpenJDK Runtime Environment 18.9 (build 11.0.3+7-LTS) +OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing) + + + If there are multiple java versions installed, switch + between them using the following command: + + alternatives --config java + + Optionally, the user can switch between the + javac versions using: + + alternatives --config javac + + + + + The following system variables need to point to the OpenJDK 11 + installation: + + export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which javac))))) +export PATH=$PATH:$JAVA_HOME/bin +export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar + + Store updates of the variables PATH, + JAVA_HOME, and CLASSPATH in + the .bash_profile file of the root user. + + + In order to make these system variables persistent, the + commands given above should be added to a script in the + /etc/profile.d/ folder. Sudo access is needed for this + operation. + + + + + The uCPE Manager requires a specific PostgreeSQL version. This is + embedded in the uCPE Manager installation. In order to avoid conflicts, + any existing installation needs to be uninstalled. + + Uninstalling PostgreSQL + + + + Open a terminal with administrative rights, i.e. log into a + bash shell with root privileges. + + + + Execute the following command to check if you have a currently + running the PostgreSQL database server: + + ps -ef | grep post + + + + Remove the currently installed PostgreSQL server (including + the existing postgres user): + + yum remove postgres\* +rm -f /var/lib/pgsql +rm -f /etc/postgres-reg.ini +userdel postgres + + + This step is not necessary if the uCPE Manager will be using + an external database (like MariaDB). + + + + + If you have multiple spindles, it is recommended to let the + application run off one and the database off the other. This will result + in optimum performance. It is also recommended that the swap disk be the + same as the one used for the application. + + Assuming another spindle is used (/drive2) do + the following: + + + + Create a folder which will host the database (e.g. + emsDatabase). + + + + Create a soft-link that will point to this folder: + + ln -s /opt/ems/elementcenter/database /drive2/emsDatabase + + + + Follow the installation process as described below. + + +
+
+ +
+ uCPE Device configuration + +
+ Determining the WAN and LAN ports + + A typical White box comes with multiple physical network ports, + ready to be used. The user must determine the purpose and allocation of + each port. The allocation is later aligned with the software + configuration within the Enea NFV Access installer. + + A common way is to allocate the left ports to WANs and the right + ports to LANs. At least one port must be allocated to WAN and one to + LAN. +
+ +
+ Determining the uCPE Identifier + + Each uCPE device needs a unique identifier. This identifier is + used to match the registration in the uCPE Manager and the offline + configuration of the uCPE device during ZTP (Zero Touch + Provisioning) + + Select a text string to represent the uCPE device, e.g. + uCPE-1 or + fwa-t1012vc_boston_1234. +
+ +
+ Configuring the BIOS + + The factory configuration of the BIOS may not match the + requirements of Enea NFV Access. The BIOS configuration needs to be + reviewed and potentially reconfigured to prepare for a successful + installation. + + Access the BIOS using a serial cable between the uCPE device and + the laptop, to review and configure the BIOS correctly. The White box + vendor is expected to provide the right serial cable for the box. A + terminal emulator (such as putty) is needed on the laptop. + + Enable the following BIOS features/configurations: + + + + EFI + + + + Intel Virtualization Technology (VT-x) + + + + Intel Virtualization Technology for Directed I/O (VT-d) + + + + SR-IOV + + + + The boot order may also need to be modified to support + installation and execution of the Enea NFV Access Runtime Platform on + the uCPE device. + + The following boot order is recommended for a base + configuration: + + + + Boot from USB + + + + Boot from Disk + + + + With the above boot order there is no need for a configuration of + the BIOS during installation and deployment. +
+
+ +
+ Preparing the deployment + +
+ Installing the uCPE Manager + + On the CentOS 7 server open a terminal, log into a bash shell with + the root account and perform the following: + + + + Unzip + Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz + + The directory in which the archive has been unpacked will be + denoted as: <uCPEM-installdir>. + + + + Enter <uCPEM-installdir>. + + + + Choose the target installation folder, e.g. + /opt/ems. Everything will be installed under a + folder called /ucpemanager within the target + installation folder. + + The application files will be installed in + /opt/ems/ucpemanager/application. The database + will be installed in + /opt/ems/ucpemanager/database. + + + + Run the following interactive command: + + ./install.sh /opt/ems \ +Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz + + Use the default configuration values provided below in the + interactive install command. The same configuration values will need + to be provided when upgrading or uninstalling the uCPE + Manager: + + + + Database Configurations: + + + + Are you using the embedded PostgreSQL database? [Y/N]: + Y. + + + + Specify the database process password: + postgres. + + + + Specify the database ID (or name): + ucpemanager. + + + + Specify the database server port: + 5432. + + + + Specify the database user name: + postgres. + + + + Specify database password: + postgres. + + + + Specify database startup thread pool size: + 1. + + + + + + Service Configurations: + + + + Specify service username: + ucpemanager. + + + + Specify service password: + ucpemanager. + + + + + + High Availability Configurations: + + + + Specify the IP address of the local interface: The + CentOS 7 loopback address: 127.0.0.1. + + + + Is this server part of a cluster? [Y/N]: + N. + + + + + + Heap Configuration: + + + + Please enter the new Maximum Heap Size: 4 + GB.Is this value accurate? + + + + + + This command will: + + + + Extract the application files from the compressed + installation kit. + + + + Install the bundled database. + + + + Install the uCPE Manager as a service with the name + ucpemanager. + + + + Start the ucpemanager service + + + + + + Open the IP Address of the CentOS 7 in a web browser on the + laptop and log in with the username and password: + admin/admin. + + + + + The IPv4 address of the CentOS 7 server, connected to the same + network as the uCPE Devices, will be used as a configuration parameter + both when setting up the uCPE devices and when accessing the uCPE + Manager GUI. + + + The uCPE Manager can be restored if a back-up file has been + previously created. A backup file can be created by accessing from the + uCPE Manager GUI: System -> System + Backup. The resulting zip archive will be located in the + /opt/ems/ucpemanager/application/backup folder and + will be named SystemBackup_MMMDD_YYYY_HHMM_SS.zip + (e.g System-Backup_Feb19_2013_2257_42.zip). Save the archive to another + location outside the uCPE Manager installation folder for future + use. + + + The System Back-up file obtained from the uCPE Manager GUI + (SystemBackup_MMMDD_YYYY_HHMM_SS.zip) must be + used to recover the uCPE Manager during deployment. + + This is different from the uCPE Manager snapshot obtained during + a uCPE Manager Upgrade or Uninstall Operation + (ucpemanager-Backup-YYYYddMMHHmm.tar.gz).Why + do both options exist, what makes them different from each + other? + + + To install the uCPE Manager with the restore option provide an + additional argument as shown below during installation: + + ./install.sh \ +/opt/ems Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz \ +SystemBackup_MMMDD_YYYY_HHMM_SS.zip +
+ +
+ Preparing the USB stick for installation of the NFV Access Run + Time Platform + + To install the Enea NFV Access Run Time Platform, create a + bootable USB stick with the image you intend to install. Follow the + example below to proceed. + + + The .hddimg image is available in the + Enea_NFV_Access_Run_Time_Platform_ + <processor>_<version>-build<build_number>.tar.gz + file you downloaded with your release. + + + Create a bootable USB stick + image + + + + Copy the .hddimg image file provided by + Enea, into the CentOS 7 server. + + + + Connect the USB stick to the CentOS 7 Server and identify the + USB device name given by the system with + lsblk: + + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +sda 8:0 1 28.7G 0 disk +sdb 8:0 0 111.8G 0 disk +|-sdb1 8:1 0 111.8G 0 part + + + + Copy the .hddimg image onto the USB + stick, e.g: + + sudo dd if=./enea-nfv-access-<machine>.hddimg \ +of=/dev/sdb bs=4M conv=fsync + + Where + enea-nfv-access-<machine>.hddimg is the + .hddimg file and sdb is the + assigned USB device name. + + +
+ +
+ Preparing physical deployment for installation + +
+ Preparing for Hardware Installation + + + + + + +
+ + The following hardware configuration is needed to install uCPE + devices: + + + + Network connection between the CentOS 7 server and the + laptop. + + + + The uCPE device is powered off. + + + + Direct Ethernet cable connection between the uCPE Device LAN + and the laptop. + + +
+ +
+ Installing Enea NFV Access - uCPE Device installation + + To initiate the installation of the NFV Access Run Time Platform + do the following: + + + + Plug the USB stick into the uCPE device. + + + + Connect a laptop directly into one of the uCPE device ports. + This can't be used as a WAN port at a later moment. No other ports + should be connected. + + + + Power up the uCPE device and boot the USB stick. + + + + The Web-installer application will start automatically and can + be accessed in a web browser on the laptop at + http://172.16.1.1 (port 80). + + + + On the first page of the Web-installer, the user must fill + in: + + + + The static uCPE Manager IP Address. + + + + The unique identifier of the uCPE device (called "uCPE + Identifier" in this guide). + + + + Customer Tags. They are used for Zero Touch Provisining + (ZTP) and can be left empty for a base configuration. What can + be entered here (if needed), are the tag(s) specified when + creating an offline configuration in the uCPE Manager. A later + addition of customer tags can only be done by reinstalling the + uCPE devices. + + + + + + On the second page of the Web-installer, the user must fill + in: + + + + The Layer 3 configuration of WAN Interface(s). + + + + The Static or Dynamic IP. + + + + During network configuration, WAN cables are plugged into + the uCPE device to identify ports and make them available for + configuration. All ports with cable connections will be set as + WAN ports and must be configured (DHCP is the default setting). + The configured WAN ports cannot be removed after configuration. + The user needs to connect the same number of cables as the + number of WAN ports that he wishes to configure. The configured + WAN cables cannot be removed after being configured. + + + No LAN ports should be connected nor configured at this + time. The LAN port used to access the Web-installer from the + laptop will not be shown and cannot be configured in the Web + Installer. + + + + + The Management Interface. The network interface (IP + Address of the uCPE Manager) used by the uCPE Manager to + communicate with the uCPE device. + + + + + + When the user has completed the configuration steps in the + Web-installer, NFV Access is installed on the hard drive. The largest + drive found on the uCPE device will be used for installation. +
+ +
+ Preparing physical deployment for execution + +
+ Preparing for Deployment Execution + + + + + + +
+ + The following hardware configuration is needed for service + deployment: + + + + Network connection between the CentOS 7 server and the + laptop. + + + + Network connection between the CentOS 7 server and the uCPE + device WAN port. + + + + One uCPE device LAN connected to the laptop using an ethernet + cable. + + + + The USB is removed from the uCPE device. + + + + The uCPE device powered off. + + +
+
+ +
+ Management of uCPE Devices + + When the installation is complete the uCPE Device can be connected + to uCPE Manager. + +
+ Add a default Offline Configuration + + Zero Touch Provisioning is always turned on when a uCPE device + connects to the uCPE Manager. To enable it in the uCPE Manager, an + offline configuration needs to be registered for Day-0 + configuration. + + + Day-0 configuration is a software lifecycle term referring to + early configurations to put the uCPE device in an active state. Day-1 + Configurations are applied after Day-0 and set the uCPE device and its + service in an active state. Day-2 Configurations are live + configurations on the uCPE and its service, applied after the uCPE + device and its service have been activated. + + + The offline configuration consists of data and parameters that are + meant to be automatically set when a uCPE device connects to the uCPE + Manager for the first time. The configuration is typically focused on + setting up the network management of the uCPE device, e.g. configuring + network interfaces, WAN and LAN networking and service chains. + + For this base configuration, the offline configuration will be + left blank. The blank offline configuration can be filled with + user-specific values and data once the service is created, which is done + after installation is complete. + + + If the offline configuration is not configured, an alarm will be + raised: Day-0 Config:ZTP:Major when the uCPE device + tries to connect to uCPE Manager, informing the user that the ZTP + setup failed for the uCPE device. + + + To create an offline + configuration + + In a browser access the uCPE Manager, then + Applications->Offline + Config. + + + + Create a new offline configuration in the GUI by clicking + Add and filling in the mandatory fields: + name, deviceVersion and + deviceId. + + The name is user defined and can be set to any unique text + string identifying the configuration. The deviceVersion must match + the Enea NFV Access version of the uCPE device and the deviceId + must be set to the previously set identifier of the uCPE (uCPE + Identifier). + + +
+ +
+ Add a uCPE device to the Management System + + The uCPE Manager will periodically poll the uCPE device based on + the IP address broadcasted by the uCPE device, attempting to establish a + management connection. + + For the connection to succeed, add the uCPE device running the NFV + Access Run Time Platform to the management system: + Devices -> Manage -> + Add. Supply information about the uCPE device and set + the parameters that will be used to connect to it. + + The relevant parameters are: + + + + Type. The type of device to + be added, i.e Enea universal CPE. + + + + Name. The name by which the + uCPE device is referred to in the uCPE Manager. + + + + SSH Port. The NETCONF Port + used for communications. Default is set to 830. + + + + SSH User Name. The user name + for SSH connectivity. Default user is root. + + + + SSH Password. Leave this + blank. + + + + Device Calls Home. This + checkbox indicates the direction of uCPE device communications. For + a base configuration, leave this flag unchecked. + + + + Device ID. The unique + identifier of the uCPE device. + + +
+ +
+ Booting the uCPE device and adding it to the Map + + When connectivity is established with the uCPE Manager and a uCPE + device is already registered with a matching Device + ID, the installation is complete, and the connection is + established. + + + In case of failure due to a misconfiguration or if a uCPE device + does not appear in the uCPE Manager, a reinstallation is needed .The + user should remove all WAN cables, reinsert the USB stick, reattach + the laptop, reboot the uCPE device and then access the Web-installer + (http://172.16.1.1). If the uCPE device does not + appear in the uCPE Manager then a reinstallation is needed. + + + When a uCPE device is registered it can be manually added to the + map for overview. Right-click on the map and select Place + Device to put the uCPE device on the map. +
+
+ +
+ uCPE Device Monitorization and Control + + Once the uCPE device is connected to the uCPE Manager, it is ready + for central management. Two important functions available in the uCPE + Manager GUI are alarm checking and resource allocation. + +
+ Checking Alarms + + The uCPE Manager dashboard presents alarms in a specific window on + the front page. + + An alarm can be easily triggered by disconnecting and reconnecting + the WAN ethernet cable from the uCPE device. The management system will + detect the broken link and raise an alarm: Device + Disconnected::Critical. + + A separate Alarm Management window can be accessed from the uCPE + Manager menu for in-depth access and programming of Alarms and + Events. +
+ +
+ Checking uCPE device Resource Allocation + + When the uCPE device is connected to the uCPE Manager it is of + interest to check the amount of hardware resources in use. + + To check CPU, RAM and disk utilization simply select the uCPE + device and click the Virtual Machines tab in the map + view. The same view will show active VNFs running on the uCPE device + once instantiated. +
+ +
+ Accessing the uCPE device CLI + + As a final check to make sure the uCPE device was installed + correctly, access its Linux CLI by marking the uCPE device on the map + and selecting SSH from the panel. A new window will + appear for CLI access. The default user and password are + root and blank, respectively. + + The Enea NFV Access CLI is a pure Linux CLI providing access to + standard Linux CLI commands. The CLI is a central feature for running + custom scripting. +
+
+ \ 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 @@ - Introduction + Overview - Enea NFV Access for universal Customer Premise Equipment (uCPE) is a - virtualization and management platform, which allows end-users to introduce, - instantiate, and run third-party VNFs onto their systems. It is comprised of - two major components working in close cooperation: + This document describes the Enea NFV Access and provides installation + steps for deploying a base configuration in order to create: - The Enea NFV Access Run-Time Platform, which acts as the host for - Virtualized Network Functions (VNFs) and provides management over - NETCONF. + A functional uCPE Management installation ready to manage uCPE + devices. - The Enea uCPE Manager, a solution that runs on an external server, - providing VNF Management functionality and managing large numbers of - uCPEs. + One or several managed uCPE devices, ready to host network + services, using one wired WAN and one wired LAN connection. + + + + One laptop accessing both the uCPE Manager and the uCPE + device. -
- Enea NFV Access Run Time Platform + Extended deployment and configuration options are also detailed in the + following chapters. + +
+ Enea NFV Access + + Enea NFV Access for universal Customer Premise Equipment (uCPE) is a + virtualization and management platform, which allows end-users to onboard, + instantiate, and run third-party VNFs onto their systems. It is comprised + of two major components working in close cooperation: + + + + The Enea NFV Access Run-Time Platform, which acts as the host + for Virtualized Network Functions (VNFs) and provides management over + NETCONF. + + + + The Enea uCPE Manager, a solution that runs on an external + server, used for VNF Management and managing large numbers of uCPE + devices. + + + + In addition, Enea NFV Access also includes a software framework for + Automation and Testing (AFTH). More information can be found in + . + + Details concerning release content, including documentation + structure, are provided in the manual included + with your release. + +
+ Enea NFV Access Run Time Platform + + The Enea NFV Access Run Time Platform is a lightweight, + multi-architecture virtualization platform, supporting Virtual Machines + (KVM / QEMU) and container(s) (Docker). Designed for a low footprint and + fast boot by only providing essential functionality. + + The NFV Access virtualized data plane has DPDK and accelerated OVS + as its primary components. The data plane is highly optimized for + scenarios where high throughput and low latency are needed. - Enea NFV Access Run Time Platform is a lightweight, - multi-architecture virtualization platform, supporting Virtual Machines - (KVM / QEMU) and container(s) (Docker). Designed for a low footprint and - fast boot by only providing essential functionality. + VNF Runtime Management, orchestration integration, and FCAPS are + provided through NETCONF. - The NFV Access virtualized data plane has DPDK and accelerated OVS - as its primary components. The data plane is highly optimized for - scenarios where high throughput and low latency are needed. +
+ VNF Space - VNF Runtime Management, orchestration integration, and FCAPS are - provided through EdgeLink NETCONF. + + + + + +
+
-
- VNF Space +
+ Enea uCPE Manager - - - - - -
+ The Enea uCPE Manager is a control center application providing a + full FCAPS and VNF management experience through a GUI and REST API. It + can be deployed on a host or a virtual machine running 64-bit CentOS 7 + on an x86 platform. The uCPE Manager uses a southbound NETCONF protocol + to connect and manage uCPE devices. + + The Enea uCPE Manager provides the following key features: + + + + VNF Onboarding + + + + VNF Management + + + + FCAPS + + + + Zero Touch Provisioning + + + + Alarms / Events management and monitoring + + +
-
- Enea uCPE Manager +
+ Definitions and Acronyms - Enea uCPE Manager is a control center application providing a full - FCAPS and VNF management experience through a GUI and REST API. It can be - deployed on a host or a virtual machine running 64-bit CentOS on an x86 - platform. The uCPE Manager uses a southbound EdgeLink NETCONF protocol to - connect and manage uCPE devices. +
+ Definitions - Enea uCPE Manager provides the following key features: + + Definitions - - - VNF On-boarding - + + - - VNF Management - + - - FCAPS - + + + Enea NFV Access - - Zero Touch Provisioning - + The Enea NFV Access Run Time Platform and the uCPE + Manager. + - - Alarms / Events management and monitoring - - + + Enea NFV Access Run Time Platform + + A lightweight, multi-architecture virtualization + platform, supporting Virtual Machines. + + + + Enea uCPE Manager + + Enea Universal Customer Premises Equipment + Manager. + + + + PCI Passthrough + + PCI Passthrough allows for use of a physical PCI device, + e.g. a network card inside a VM. If you "PCI passthrough" a + device, the device is not available to the host anymore. + + + + uCPE device + + A whitebox running the Enea NFV Access Run Time + Platform. + + + +
+
+ +
+ Acronyms + + + Acronyms + + + + + + + + + API + + Application Programming Interface. + + + + DPDK + + Data Plane Development Kit. + + + + EFI + + Extensible Firmware Interface. + + + + FCAPS + + Fault-management, Configuration, Accounting, Performance + and Security. + + + + NETCONF + + Network Configuration Protocol. + + + + NFV + + Network Functions Virtualization. + + + + OVS + + Open vSwitch. + + + + UEFI + + Unified Extensible Firmware Interface. + + + + SR-IOV + + Single Root Input/Output Virtualization. + + + + PCI + + Peripheral Component Interconnect. + + + + REST + + Representational State Transfer. + + + + VNF + + Virtual Network Function. + + + +
+
- + \ 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 @@ + + + Using the Log Collector + + Troubleshooting problems on the uCPE device require an analysis of a + set of information i.e. logs collected from the uCPE device and/or uCPE + Manager. The following describe how the log collection mechanism + works. + +
+ Log collecting using the uCPE Manager + + The uCPE Manager allows for collection of the relevant logs from the + GUI. Collect the necessary log files and system details, then create an + archive (a tar file) on the uCPE device in the + /var/odm/log/archives folder: + + + + Access Operations -> Collect + Debug Logs. + + + + Provide a file name in the new window. + + + + Press the Execute button. + + A success message is shown in the same window as shown below. At + this moment, the process of collecting logs on the uCPE device + starts. + + +
+ Collecting Debug Logs + + + + + + +
+ + + + It might take some time for the archive to be created. When the + operation completes, a "CollectLogsComplete" notification is sent from + the uCPE device to the uCPE Manager. This can be viewed in the GUI under + the Faults -> Events toolbar + menu. + +
+ Collecting Debug Logs + + + + + + +
+ +
+ +
+ View collected logs + + A list with the archives containing already collected logs will be + shown in the Device File Listing table: + + + + Access Files -> + Download. + + + + Press the List button. + +
+ Device File Listing Table + + + + + + +
+ + + + + If the filename you specified does not appear, it might still be + in the process of creation. Click on the Refresh icon + at the bottom of the table until you can see the desired file + listing. + +
+ +
+ Downloading Logs from the uCPE Device + + This option transfers a debug file archive from the uCPE device to + uCPE Manager machine. + + + + Access Files -> + Download. + + + + Press the List button. + + + + In the Device File Listing table, select the + archive you want to download from the uCPE device to uCPE + Manager. + + + + Press the Download from Device button. + + The archive will be downloaded from the uCPE device and stored + on the uCPE Machine. + + + + + The archive will not be deleted from the uCPE device after + download. + +
+ +
+ Downloading collected logs locally + + This option downloads a logs archive from the uCPE Manager to a + local (user) machine for analysis. The archive must first be available in + the uCPE Manager in order to be downloaded. + + + + Access Devices -> + Files. + + + + Select the Downloaded Files tab. + + + + Select an archive from Downloaded Files + table. + + + + Click the Download button. + + The file will be downloaded in browser's download folder. + +
+ Downloaded Files Table + + + + + + +
+ + +
+ +
+ Deleting a logs archive from a uCPE device + + Use this option when you want to delete unnecessary collected logs + on the uCPE device. + + + + Access Files -> + Download. + + + + Press the List button. + + + + In the Device File Listing table, select the + archive you want to delete from the uCPE device. + + + + Press the Delete button. + + The archive will be deleted from the uCPE device and the table + will be updated. + + + + The same can be achieved using these alternative options: + + + + Access Operations -> Delete Debug + Log Archive. + + + + Provide a file name in the new window. + + + + Press the Execute button. + + A success message is displayed if the file is deleted from the + uCPE device correctly. + + +
+ +
+ Deleting logs archives from the uCPE Manager + + This option deletes a logs archive from the uCPE Manager. + + + + Access Devices -> + Files. + + + + Select the Downloaded Files tab. + + + + Select an archive from the Downloaded Files + table. + + + + Click the Delete button. + + The file will be deleted from the uCPE Manager and the table + will be updated. + + + + + Deleting the logs file from the uCPE Manager does not affect the + file located on the uCPE device. + +
+ +
+ Enabling/Disabling of the Log Collector via Permissions + + To disable the ability to access/download the uCPE device's + debug-log files from the uCPE Manager, the appropriate permissions must be + changed: + + + + Access Security -> + Configuration. + + + + Click the Security Groups tab. + + + + Click the desired group. + + + + Click the Permissions tab on the right + side. + + + + Click the Devices tab like in the image + below. + + + + Change the Device File Management option to + none to disable the feature. + + + +
+ Device File Management + + + + + + +
+
+ +
+ Downloading uCPE Manager logs + + Often, sending the uCPE Manager logs together with collected uCPE + device logs to the support team provides important information for + troubleshooting (especially in cases of connectivity issues with the uCPE + device and error popups). + + uCPE Manager log files are located in + application/logs/ in the uCPE Manager's installation + folder (e.g./opt/ems/ucpemanager/application/logs). + They can be copied from that location, or they can be downloaded using the + uCPE Manager GUI by performing the following: + + + + Access Test -> Debug + Settings and select the Log Files + tab. + + + + Select the desired log file + (ucpemanager.log or + watchdog.log) and press the + Download button. + + + + A new (blank) popup window opens and the file is downloaded + locally. This popup can be closed after the download. + + + + Repeat steps 2. And 3. Until all the desired log files have been + downloaded + + + +
+ Debug Settings + + + + + + +
+
+ +
+ Log collecting without using the uCPE Manager + + Log collection from uCPE Devices can also be done when there is no + uCPE Manager connection. A SSH connection to uCPE Device is needed for use + of the log collector script, which can be found in the uCPE Device file + system in /usr/local/enea/. + + The Log collector script takes relevant information about the system + and collects it in an archive: + + ./log-collector.sh -p <LOG_PATHh> -n <ARCHIVE_NAME> + + Where -p is the path where the log archive will + be saved, -n is the archive name. + + + If -p is not provided, the default path will be + used: /var/logcollector. If -n is + not provided, the default name will be used: + log_archive_<timestamp>.tar.gz. + + + To access the help menu of the script: + + ./log-collector.sh -h +
+ \ 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 @@ + + + Network Configuration Options + + Various Advanced Network Configuration options can be done from uCPE + Manager GUI. + +
+ Device Call Home Connection for deployment behind NAT + + The Device Call Home option enables the initiation of the connection + between the uCPE Device and the uCPE Manager, from the uCPE device. The + Device Call Home option is required when deploying a uCPE device behind + NAT since the IP address of the uCPE device is hidden for the uCPE + Manager. + + Enable Device Call Home by marking the Device Call Home checkbox + when registering the uCPE device in uCPE Manager. When using this + mechanism, the device will initiate a connection to the uCPE Manager for + NETCONF traffic (over SSH), while the uCPE Manager waits for a device + connection. +
+ +
+ uCPE Device Network Configuration + + The following describes the steps required for setting up the + virtualization infrastructure, ensuring that a uCPE device has networking + setup for virtualized service deployment. Networking is enabled by + selecting physical interfaces to be used by virtualized networking and + creating different types of bridges to enable VNF communication. + + The Zero Touch Provisioning mechanism is also touched upon, as + alternative to manual configuration of the virtualization + infrastructure. + +
+ Configure DPDK + + DPDK is an important functionality for accelerating networking + performance. The DPDK is enabled by default and should be utilized in + most configurations. + + In use cases where CPU capacity is very limited, disabling DPDK + can free up CPU capacity and overall performance can improve. Navigate + to Configuration -> DPDK and + deselect Enable DPDK to disable the DPDK. + + + Disabling the DPDK cannot be done after other network + configurations have been made. + + + In Configuration -> DPDK + it is also possible to configure DPDK resources such as: + + + + LCore Mask. Allocated cores + for DPDK management functions (CPU core bitmask). Default: + 0x2. + + + + PMD CPU Mask. Allocated cores + for DPDK packet processing (CPU core bitmask). Default: 0x4. + + + + Socket Memory. Allocated + memory to use. Default: 1494. + + +
+ +
+ Configure External Interfaces + + Once a management connection with the uCPE device has been + established by using any of the supported methods, the virtualization + networking infrastructure can be configured either manually or by using + Zero Touch Provisioning. + + Available network interfaces can be added to the management + system, for use by the networking virtualization infrastructure. + + In order to make physical network interfaces available to the + virtualization infrastructure and VNFs, they must be configured into the + management system. + + To add an interface into the uCPE Manager, select the uCPE device, + then from the top toolbar select Configuration -> External + Interfaces -> Configuration -> Add. The available + Interface types are detailed below. + +
+ DPDK Interface Type + + Configuring a physical interface in DPDK mode will require a + DPDK-based application (e.g. OVS-DPDK) in order to access and use the + interface. An interface set as DPDK can be attached to an OVS-DPDK + bridge. + + + Make sure the Enable DPDK checkbox is + selected in Device -> Configuration -> + DPDK, otherwise no interface can be assigned as + DPDK. + + + To add a DPDK interface under the management system, set + appropriate values for the following fields: + + + + Source: name of the physical interface. + + + + Type: dpdk + + + + Networking-type: dpdk + + + + Dpdk-type: the kernel module that allows user space access + to the physical interface. Either the vfio-pci + (most commonly used type) or the igb_uio driver + can be used. + + +
+ +
+ SR-IOV Interface Type + + SR-IOV technology allows for the creation of a number of virtual + functions on the host interface, which can be used by VNFs running on + the uCPE device. + + For SR-IOV mode configuration, the user must set values for the + following fields: + + + + Source: name of the physical interface. + + + + Type: sr-iov + + + + Networking-type: srIov + + + + sriov-mode: adapter-pool + + + + sriov-num-vfs: the number of virtual functions to + create. + + +
+ +
+ Standard Interface Type + + Some of the physical network interfaces available on a uCPE + device, including Ethernet interfaces, do not have DPDK or SR-IOV + support. Instead, the Linux kernel driver has to be used. Wi-Fi and + 4G/LTE modems can also be configured and used for virtualization + infrastructure and VNFs. + + To add Standard Interfaces under the management system, the user + must set values for the following fields: + + + + Source: the name of physical interface. + + + + Networking-type: standard. + + +
+ +
+ PCI Passthrough Interface Type + + For the PCI Passthrough a user does not have to configure a + physical interface, instead simply select the PCI address and connect + it to a virtual port when the VNF instantiation step is + reached. +
+ +
+ Manual Configuration + + For Manual Configuration of uCPE networking, select the uCPE + device first and then Configuration -> + External Interfaces, where one can find a list of + available network interfaces and their capabilities. + +
+ Configuring Interfaces + + After networking interfaces have been added to the uCPE + Manager, the user can change the interface type (DPDK, SR-IOV, + Standard, WAN). + + + WAN interfaces, which are configured during the installation + of the device, do not need to be added, they will be automatically + listed as such in the uCPE Manager when the device + connects. + + +
+ Configuration of External Interfaces + + + + + + +
+ + How to Edit the Configuration of an + Interface + + + + To edit an interface configuration type from the uCPE + Manager, select the uCPE device, then from the top toolbar + select the Configuration menu then + External Interfaces -> Configuration. The + already configured interfaces are displayed here, as can be seen + in the figure above. + + + + In order to edit an already configured interface, (as in + the example popup shown below, a WAN interface) double click on + the desired one and a popup will appear. A different popup + appears for each type of interface. From the Host + Interface window, a user can change the networking + type and the IP address assignment: + +
+ Editing an Interface + + + + + + +
+ + + + + The IP address assignment of an interface can be set as + static or dynamic for each type of interface. + +
+ +
+ Configuring Bridges + + After networking interfaces have been added to the uCPE + Manager, the user can create the necessary OVS bridges. + +
+ OVS Bridges + + + + + + +
+ + How to add OVS bridges in the uCPE + Manager + + + + Select the uCPE device. + + + + Select Configuration. + + + + Click OpenvSwitch. + + + + Select the Bridges option, then click + Add. + + + + + Depending on the settings in Configuration -> + OpenVSwitch -> DPDK, OVS bridges with or without DPDK + support will be used on the uCPE device. + + + There are three types of bridges which can be created, each + one fulfiling a different role. + +
+ uCPE In-band Management bridge + + In-band Management refers to a model where both the data + plane and control plane flow over the same network path. In some + situations (e.g. the uCPE device has only one routable IP + address), this is the only option available to both control and + configure the uCPE device, while also allowing for data-path + traffic to pass over the same physical interface. + + The solution provided by Enea for in-band management is + based upon an OpenvSwitch bridge fielding all traffic passing + through the WAN physical port. Any standard or DPDK-assigned + network interface can be used for the In-Band management + bridge. + + + The In-band Management bridge must be recreated each time + the uCPE Manager IP address is changed. + + + To create the In-Band Management bridge, the user must set + values for the following fields: + + + + name: name of the bridge. + + + + ovs-bridge-type: inbandMgmt + + + + + The first VNF instantiated on the uCPE device must be + connected to the In-Band Management bridge and its WAN interface + must be configured as the DHCP client. + +
+ +
+ In-band Management bridge for VNFs + + If VNF management can be done over a dedicated virtual + interface, its possible to extend the networking infrastructure + configuration to also access the VNF's management interface over + the WAN port. + + For this setup, three types of traffic will pass over the + WAN physical interface: + + + + Device management. Part + of the device configuration done by the uCPE Manager. + + + + VNF(s) management. + Enabling or disabling features of a VNF. E.g. + enabling/disabling the firewall or VPN setup. + + + + Data-path. All other + traffic that is not used in the control plane and needs to + reach a LAN network. + + + + To create a VNF In-Band Management bridge, the user must set + values for the following fields: + + + + name: name of the bridge. + + + + ovs-bridge-type: vnfMgmt + + + + vnf-mgmt-address: select IPv4 as the type and fill in + the IP address for management network, e.g 10.0.0.1. + + + + + VNF management interfaces must be configured in same + network as the vnf-mgmt-address of the + bridge. + +
+ +
+ Data-plane Bridge + + Data-plane bridges are generic bridges used for the VNF + data-plane. There are two supported sub-types: + + + + communication: allows + for VNF communication towards LAN/WAN networks. This bridge + type has at least one physical port attached to it. + + + + integration: allows for + VNF-to-VNF communication (usually for service function + chaining). This bridge type does not have any physical port + attached. + + + + To create a Data-plane bridge, the user must set values for + the following fields: + + + + name: name of the bridge. + + + + ovs-bridge-type: select communication + or integration, depending on intended + usage. For communication bridges, physical interfaces can be + added to the bridge. + + +
+
+
+ +
+ Zero Touch Provisioning - Creating an offline + configuration + + Zero-Touch Provisioning (ZTP) refers to the process of when a + device starts up for the first time and its initial configuration is + pushed down by an external management system, so that it is setup for + proper operation without additional manual intervention by an + operator. ZTP is an alternative to Manual configuration. + + A variety of operations can occur as part of ZTP such as initial + device setup, configuration of managed objects, etc. The goal is to + set up a device to the maximum possible extent without forcing an + operator to be physically present (initially) to manage the + device. + + An offline configuration is usually prepared in advance for the + uCPE Manager to setup the virtualization infrastructure on the uCPE + device, as soon as a device enrolls into the management system. + +
+ Offline Configuration + + The Offline Configuration subsystem is used to pre-populate a + configuration for a device that will be brought under management at + a future point in time. When creating an offline configuration store + a Device ID can be specified. This ID uniquely + identifies the device to be initialized. + + Alternatively, a wildcard can be used in the Device + ID field, which results in a configuration being pushed on + all uCPE devices upon their initial connection towards the uCPE + Manager. + + If the offline configuration is not configured for a uCPE + device, an alarm will be raised: Day-0 + Config:ZTP:Major, which occurs when the uCPE device + connects to the uCPE Manager informing that the ZTP setup failed for + the specific uCPE device. + + To create an offline configuration, from the top toolbar menu + select Applications -> Offline + Config -> Add. The following fields + should be filled: + + + + Name: name of the device. + + + + Device type: Enea universal CPE. + + + + DeviceVersion: + + + + Config Set: uCPE Config + + + + Device ID: device ID or a wildcard(*). + + + + Device Grouping Tags: a tag to group devices. These tags + match the customer tags provided during the installation of the + device. + + + + The Name is user defined and can be set to any unique text + string identifying the configuration. The Device Version will match + the Enea NFV Access version of the uCPE device and the Device ID + will be set to the previously set identifier of the uCPE + device. + + When a device connects to the uCPE Manager for the first time, + it checks the device to see if it has been Zero Touch Provisioned + (ZTP). If not, it looks for an offline configuration that matches + these values, in the following order: + + + + The Device ID. + + + + The set of tags. + + + + A "*" for Device ID (wildcard). + + + + If a match is found, the offline configuration is sent to the + device as part of Zero-Touch-Provisioning. + + After creating the Offline Config Store, access the device + through Applications -> offline + config -> Config App and provision + it with the required initial configuration. This operation mirrors + what happens during manual configuration described + previously. + + + The ZTP will only be triggered the first time a uCPE device + connects to the uCPE Manager. Just changing an offline + configuration will not push the new changes to the device. If an + offline configuration is changed after uCPE device registration, a + factory reset can be executed to force a new ZTP to execute by + selecting the device, then Operations -> + factory reset. + +
+
+ +
+ Custom Scripts for Custom Networking Configurations + + The custom scripts feature allows users to execute user-defined + scripts on the uCPE device at various times.This allows for more + flexible and advanced configurations such as a LTE modem + configuration, advanced network configurations or OVS flow rule + programming at any time. + +
+ Uploading Scripts + + The scripts need to be uploaded to the uCPE Manager prior to + use. When uploading scripts to the uCPE Manager make sure to select + the right script type. + + The following script types are supported: + + + + Once-before-startup. This script will + only execute once during the startup. + + + + Always-before-startup. This script will + always execute during the startup. + + + + Once-after-startup. This script will + only execute once after the system has been started. + + + + Always-after-startup. This script will + always execute after the system has been started. + + + + Follow the instruction below to upload scripts: + + + + Select Devices -> Custom + Scripts -> Configure. + + + + Select Upload to EMS. + + + + In the Script Type menu, select the + type the uploaded script should have. + + + + Press Choose File to select the scripts + needed, and then press Send. + + +
+ +
+ Removing Scripts + + Follow the instruction below to remove scripts: + + + + Select Devices -> Custom + Scripts -> Configure. + + + + Select the script you want to delete from the + Uploaded Scripts tab and then click + Delete, which will remove the script + immediately from the uCPE Manager. + + +
+ +
+ Configuring Script Location + + The location where the scripts are staged in the uCPE Manager + can be chanaged as described below: + + + + Select Devices -> Custom + Scripts -> Configure. + + + + Select the Configuration tab and + specify a new loacation to store the scripts. + + + Change the script storage location only if you have many + scripts which you would prefer to store on another partition, + otherwise leave this configuration as is. + + + +
+ +
+ Running the Scripts + + How to run Custom + Scripts + + + + Select Devices -> Custom + Scripts -> Apply Scripts. + + + + In the Script Config Screen pop up, + select the devices from the device(s) chooser list on which to + run the scripts. Press the > button to + move the devices to the right side of the chooser, which is the + list of devices that will execute the selected scripts. + + + + Select the scripts from the list under the device(s) + chooser by pressing the + button. + + + + In the pop-up window, select the scripts from the list. If + there are no scripts to select, then there is no script uploaded + with that particular type. Upload the script(s) needed and try + again. + + + + Check the checkbox Reboot devices if + you want to reboot and execute the scripts at once and then + press ok. + + + The status of execution for the scripts can be seen by + opening the Fault -> + Events screen and filtering by device + and/or the event name Custom. + + + +
+
+
+
+ \ 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 @@ + + + Troubleshooting and Recovery + + The following is a small list of possible NFV Access problems, and + their solutions. In all scenarios collect the logs if + possible for a later debugging. More information on log + collecting can be found in add an olink to the log collector chapter + after the olink update. + + If you encounter other issues or can't get NFV Access to work + successfully after consulting the information below, please use the Enea Support team Form, available in the + manual + downloaded with your release. + + + Troubleshooting and Recovery + + + + + + + NFV Access Problem + + Solution + + + + + + The uCPE Device cannot boot after an upgrade. + + + + Perform a hardware reboot of the uCPE Device and select + the previous NFV Access image from the GRUB menu. This action + assumes physical access to the uCPE device. + + + + Reinitiate the Upgrade procedure according to + (Link to NFV Access Getting Started -Device + Upgrade). + + + + + + After a failed uCPE device upgrade the previous NFV Access + image (from the GRUB menu) does not boot. + + Reinstall NFV Access on the uCPE device and redeploy the + initial configuration and virtualized services, by following the + Getting Started Guide.add link to Install uCPE Device. + Retitle it if need be or point to specific chapter in book with + olink + + + + The uCPE Manager upgrade fails and a working snapshot is + available. + + If a working snapshot obtained during a previous Upgrade or + Uninstall is available + (ucpemanager-Backup-YYYYddMMHHmm.tar.gz): + + + Cleanup the current upgrade attempt with: + + ./cleanup.sh /opt/ems + + + + Restore the previous installation as described in + + olink to the section/chapter: link to Restore a + previous uCPE Manager Installation + + + + + + The uCPE Manager upgrade fails and no working snapshot is + available. + + + + Cleanup the current upgrade attempt with: + + ./cleanup.sh /opt/ems + + + + Perform a installation with the restore option of a + previous uCPE Manager configuration as described in + + olink to the section/chapter describing: Installing + with the restore option. + + + + + + The uCPE device is booted, the ssh connection is available + but the device is not connected to the uCPE Manager. + + + + Perform a hardware reboot on the uCPE device to + reinitiate the connection mechanism. + + + + Use the Reconnect button from the + uCPE Manager's WEB-UI. + + + + If the above actions do not work, reinstall and + reconfigure the device using the steps provided in the + Installing the uCPE device (add link) + + + + + + The SSH connection to the device cannot be + established. + + Perform a hardware reboot on the uCPE device. If the problem + is not fixed, reinstall and reconfigure the device using the steps + provided in the Installing the uCPE device (add + link) + + + + The VNF Service is not working as expected after + reconfiguration (e.g. a VNF chain is malfunctioning). + + + + Undo all flows and/or configuration changes in order to + move the system to a previously working configuration. + + + + Reboot the device using Operations + -> Reboot menu options from within the + uCPE Manager. + + + + If the above actions do not work, redeploy all services. + This is done by cleaning up the existing configuration using: + Operations -> Factory + Reset for a specific device and redeploying the VNF + services. + + + + + +
+ \ 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 @@ + + + Upgrading NFV Access + + Enea provides regular releases that will require the upgrading of NFV + Access components. The uCPE Manager must be upgraded to the new Enea NFV + Access version before the uCPE devices are. + +
+ Upgrading the uCPE Manager + + + + Unzip the + Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz + folder. + + The directory in which the archive has been unpacked will be + denoted as <uCPEM-installdir>. + + + + Enter <uCPEM-installdir>. + + + + Run the following command with the root account and change + /opt/ems to the correct location of the uCPE + Manager installation: + + ./upgrade.sh /opt/ems \ +Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz + + + + Running this command will: + + + + Stop the currently running ucpemanager + service. + + + + Create a compressed file of the ucpemanager + application folder + (ucpemanager-Back-up-YYYYddMMHHmm.tar.gz), which + contains a snapshot of the existing installation. + + + The snapshot file created during the upgrade can be used for + restoring the uCPE Manager. + + + + + Extract the application files from the specified compressed + install kit. + + + + Start the ucpemanager service. + + + +
+ Restoring a previous uCPE Manager installation + + How to restore a previous uCPE Manager + installation + + + + Unzip + Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz + + + + The directory in which the archive has been unpacked will be + denoted as <uCPEM-installdir>. + + + + Copy the snapshot file + (ucpemanager-Backup-YYYYddMMHHmm.tar.gz) + created during a previous uCPE Manager Upgrade or uCPE Manager + Uninstall Operation into the + <uCPEM-installdir> directory. + + + + Enter <uCPEM-installdir>. + + + + Run the following command with the root user and change + /opt/ems to the correct location of the uCPE + Manager installation: + + ./restore.sh /opt/ems ucpemanager-Backup-YYYYddMMHHmm.tar.gz + + + + Running this command will: + + + + Remove any vestiges of the existing + ucpemanager service, if they exist. + + + + Reinstall the uCPE Manager application on the specified target + location, restoring the data in the database and files in the + process. + + + + The ucpemanager service will then start with + the older version now running on the system. +
+ +
+ Uninstalling an existing uCPE Manager installation + + How to uninstall an existing uCPE Manager + installation + + + + Navigate to the folder where the uCPE Manager is + installed. + + + + Run the following command with the root user and change + /opt/ems to the correct location of the uCPE + Manager installation: + + ./uninstall.sh /opt/ems + + + + Running this command will: + + + + Stop the currently running ucpemanager + service. + + + + Create a compressed file of the ucpemanager + application folder: + ucpemanager-Back-up-YYYYddMMHHmm.tar.gz, which + contains a snapshot of the existing installation and functions as a + restore point. + + + The snapshot file created during the uninstall can be used + for restoring the uCPE Manager. + + + + + Uninstall the ucpemanager service, so that + it will not startup on reboot. + + + + Uninstall the database service. + + + + Completely remove the contents of the application and database + folders. + + + + After these steps, the uCPE Manager is completely removed from the + system. +
+
+ +
+ uCPE device upgrades + + A uCPE device can be upgraded using the uCPE Manager GUI. + +
+ The uCPE device upgrade process + + The Device Upgrade/Install option performs the following + operations to the uCPE device: + + + + Prepare for upgrade. This + stage prepares the files needed for an upgrade. + + + + Install file on device. This + stage copies the file to the uCPE device. + + + + Upgrade Device. This stage + upgrades the uCPE device to a newer version. + + +
+ +
+ Managing the Device Upgrade + + Before an installation or upgrade can be completed, certain + configuration data must be set. Files also need to be uploaded to the + Device Upgrade image repository to be uploaded to the device. + + Launch the Device Upgrade management console by selecting + Devices -> Upgrade from the top + tool-bar. The console will contain the following tabs: + + + + Image Library. To add/delete an + image. + + + + Upgrade Operations. See running upgrades, + cancel any upgrades in progress, start a uCPE device upgrade. + + + + Configuration. Upgrade configuration + parameters. + + + + Press Close when the message File Uploaded + Successfully appears on the File Upload Screen. + + + The uCPE Device upgrade is done with image files of type + rootfs.ostree.tar.bz2, which are available in the + Enea_NFV_Ac-cess_uCPEManager_<version>-build<build_number>.tar.gz + file you downloaded with your release. + + +
+ Image Library + + Adding an image to the image + repository/library + + Select Devices -> + Upgrade. + + + + Select Add from the Image + Library tab to add a new image file. + + + + Click on Choose File to provide the + path to the image file (must be of type + rootfs.os-tree.tar.bz2). + + + + Select the target hardware platform corresponding to the + image being uploaded (xeon-d or + atom-c3000). + + + + Click Send to upload the image to the + image repository. + + + + Deleting an image from the image + repository + + + + Select Devices -> + Upgrade. + + + + Select the image you want to delete from the Image + Library tab and then click + Delete. + + +
+ +
+ Upgrade Operations + + The Upgrade Operations tab allows a user to + manage uCPE device upgrades in the system. It allows the user to see + all the upgrades that are currently in progress, as well as listing + the completed ones. If an upgrade succeeds or fails, then a row will + be added to the completed upgrades table. If one fails, the failure + message will be visible in the table. + + + The list of completed upgrade tasks resides in the cache + memory and will not persist across reboots of the server. + + + How to Install/Upgrade a device + immediately or schedule the process for later + + Select Devices -> + Upgrade. + + + + Select Upgrade Devices from the + Upgrade Operations tab. This will launch a + Multi Device Install Image screen that will + allow the user to install and upgrade more than one uCPE device + at a time or upgrade later. + + + + The configurable parameters are: + + + + Scheduling. Click this checkbox if the + upgrade will be done later. Schedule the day, hour and minute for + when to run the upgrade. + + + The hour represents the local uCPE Manager server + hour. + + + + + Description. An optional description of + the operation. It is recommended to add a description so that + different upgrades happening simultaneously can be + distinguished. + + + + Image File. Click on Choose + Image File to select the image file. + + + + Devices. The list of uCPE Devices that + can accept an image file is populated when the image file is + chosen. + + Press the > button to move the uCPE + devices to the right side of the selector. Those chosen form the + list of uCPE devices that will be upgraded. + + + + Upgrade Operation. The available options are: + + + + Install and Activate. This will do an + image installation as well as an upgrade. + + + + Install Only. This will do an image + installation only. The image is copied to the uCPE device, and + an upgrade will be done later either at a scheduled time or + when the option Activate Only is + selected. + + + + Activate Only. This will activate an + already installed image on the uCPE device. + + + + + + + When the uCPE device activates the upgrade, it will be + rebooted automatically. + +
+ +
+ Releases installed on a uCPE device + + The installed releases on a uCPE device can be viewed by + selecting the uCPE device first, then from the top toolbar selecting + Configuration -> + Upgrade. + + The installed releases on the uCPE device, the release status, + release state, commit-id and release version will + be listed in a table. +
+ +
+ uCPE device upgrade status + + The status of the installation and upgrade can be viewed in the + Upgrade Operations tab. Ongoing or scheduled + upgrade operations can be viewed or cancelled. + + To view the status of an installation or + upgrade operations + + + + Select Devices -> + Upgrade. + + + + Select Upgrade Operations. The ongoing + operations are listed at the top and a history of failed or + successful operations are listed at the bottom. + + + + Select an Active or Completed + Upgrade Operation and click the Device + Status button to see detailed information regarding the + upgrade operation, including the uCPE devices involved and + information per uCPE device. + + + + To cancel an upgrade + operation + + + + Select Devices -> + Upgrade -> Upgrade + Operations. + + + + Select an operation from the list and press Cancel + Upgrade and Confirm. The operation + will then be deleted from the list. + + +
+ +
+ Configuration + + + The default values present in the configuration of each uCPE + device are recommended for use. Modifying them is for an Advanced + User only. + + + How to Configure the uCPE device + Upgrade + + Select Devices -> + Upgrade. + + + + Select Configuration. + + + + The configurable parameters are: + + + + deviceImageDir. This is the disk + location of the device image repository. + + + If no absolute path name is given it is assumed to + be relative to the installation directory. + + + + + maxThreads. This number dictates + how many upgrades the system can manage at one time, either + individually launched or launched from the multi-device + screens. This value defaults to 20, which means that 20 uCPE + devices may be updated at one time. + + + + KeepAlive. This number represents + the number of seconds that a thread will be kept alive + before it is collected. If multiple installations are + occurring, this will keep the thread alive for X seconds + before it is released. If not released, it can be used by + the internal scheduling system as soon as it has completed + an upgrade. + + + + +
+ + +
+
+ \ 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 @@ + + + VNF Management + + The Enea uCPE Manager is responsible for onboarding, configuring (e.g. + CloudInit) and ensuring life cycle management of VNFs that are instantiated + and run on the various uCPE devices. + +
+ Onboarding a VNF + + The onboarding of a VNF means adding it to the Enea uCPE Manager VNF + Catalogue and preparing it for instantiation (deployment on connected uCPE + devices). This is accomplished using the Enea uCPE Manager Onboarding + graphical user interface. + + Typically, the Getting Started Guide of a VNF, provided by the VNF + vendor, contains all necessary information needed to onboard a VNF. + +
+ Retrieving Artifacts + + The user must first retrieve the necessary artifacts from the VNF + vendor: + + + + Download the VNF from the commercial vendor. + + + + Procure any VNF-specific files from the VNF vendor, e.g. + license file. + + + There are no standard ways of managing VNF licenses, + therefore no general guidelines can be provided. One example of + license handling that can be employed in the uCPE Manager is the + adding of a license during the Cloud-Init setup. + + + + + Optionally, get access to the VNF specific VNF Manager for day + 1 and 2 configuration (in cloud or for local deployment). + + + + Procure the Getting Started Guide from the VNF vendor, + preferably for KVM deployment for VNF specific configuration + information. + + +
+ +
+ Preparation + + Once all needed downloadables, documentation and more have been + attained, preparation for onboarding must be completed: + + + + Determine the use-case and performance requirements of the VNF + you wish to deploy: + + + + This decides what resources the VNF is configured for, + along with networking and day zero configurations. + + + Generally, the Getting Started Guide for the VNF + provides guidelines for resource allocation, but since + performance is dependent on hardware capacity, the right + resource allocation for deployment is determined through + benchmarking. + + + + + Determine the amount of hardware resources needed for the + VNF (RAM, number of CPUs and storage size). + + + + Determine how many Virtual Network Interfaces the VNF will + use. + + + + + + Determine the Day-0 configuration method from the VNF Getting + Started guidelines. + + + For many VNFs, day zero configuration can be skipped in + early onboarding efforts when automation is not of + importance. + + + + + Determine any requirements needed by the Cloud-Init file + structure and the content needed when this structure is used. + + +
+ +
+ Onboarding into the uCPE Manager + + How to onboard a VNF into the uCPE Manager + + + + + Select from the top toolbar VNF -> + Descriptors + + + + Click the On-board button. + + + + When prompted by the UI, make sure the VM + Image radio button at the top of the onboarding screen is + selected, it will trigger a popup menu window. + + + + This window contains data fields where both necessary and optional + information about the VNF can be supplied. After doing so, press the + Onboard button, the uCPE Manager will create the VNF descriptor and add + it to its VNF Catalog. + +
+ Onboard a VNF + + + + + + +
+ + Main fields + + + + VM Image File. This is the + Virtual Machine image file for the VNF. Typically, it is a QCOW + image. Press Choose File and select the image you + wish to upload. + + + + Image Format. Select the + format which matches the image file format. + + + + VNF Type Name. This is the + name that will be used to identify this VNF. It will be shown in the + VNFs list. + + + + Description. This field + contains any description provided and is only displayed in the GUI + tables in the uCPE Manager. + + + + Version. This is the version + of the current VNF that you are hosting. It's used to distinguish + this VNF from other versions of the same type. + + + + Memory in MB. This is the + amount of memory (in megabytes) that will be provided to this type + of VNF when it is instantiated. To determine the value for this + field, consult the VNF vendor. + + + + Num of CPUs. The number of + CPUs that will be dedicated to an instance of this VNF when created. + To determine the value for this field, consult the VNF + vendor. + + + + Storage in GB. How much disk + space to provide an instance of this VNF. To determine the value for + this field, consult the VNF vendor. + + + + Interfaces Tab + + Click on the Interfaces tab to show the + Interfaces table. + + This table will contain the interfaces required by this VNF to be + configured, when creating an instance. Consult the VNF vendor to + determine which and how many are required. Each interface requires a + name, and optionally a description, used only by the uCPE + Manager. + + + CAUTION: The user MUST conserve the same order for the virtual + interfaces during both onboarding and instantiation phases. + + + Cloud Init Tab + + Click the Clout Init tab to provide the + Clout-Init configuration. There are three fields that need to be + populated: + + + + Cloud-Init Datasource + + To onboard a VNF you must specify the Cloud-Init + Datasource that the VNF uses. This information is procured + from the VNF Vendor. Choose one of the following methods to specify + the datasource: + + + + None. If there is no + datasource. + + + + ConfigDrive. This method + allows you to provide any number of content-data files + containing Cloud-Init data. + + + + NoCloud. This is a + simpler method that uses only one cloud init file + (User-Data). + + + + ISO. Pre-cooked + cloud-init image. This image must be created by the user + according to VNF requirements. + + + + + + Cloud-Init Disk Type + + The Cloud-Init Disk Type field must be set + to either Disk, or CD-ROM, + depending on what the VNF requires. You can get this information + from the VNF Vendor. + + + + Content Files Table + + The Content Files Table is ONLY used if + ConfigDrive is chosend as the Cloud-Init + Datasource. For each content file added, a Path + must be provided. When the uCPE Manager is used to create an + instance for multiple VNFs, the user will be prompted to provide a + data file for each entry in this table. Each type of VNF will + require different cloud-init files, e.g.: a license file. The data + files will be added to the cloud-init image that the user provides + at the instantiation of the VNF. If the cloud-init image is not + provided, no Cloud-Init Data Source will be created for that VNF and + there will be no warning. + + + + Consult with the VNF vendor to determine what is required for the + VNF you are onboarding. + + Properties Tab + + In this table, you can enter values for properties that will be + used during instantiation of the VNF. The values will augment the + default values in the Domain.XML file used by + libvirt/virsh (running in NFV Access) when creating + an instance of the VNF. Consult with the VNF Vendor or ENEA support for + values needed by specific VNFs. + + Property Values + + + + numHugePages defines the number of huge + memory pages the VNF uses (for DPDK). + + + + vnfMgmtIpAddress: the IP address of the + VNF's management interface, connected to a + vnfMgmt bridge (e.g. 10.0.0.2). + + + + internalMgmtPort: the VNF's TCP/UDP port + used for management (e.g. 443). + + + + externalMgmtPort: the Management port used + for external access (e.g. 60001). + + + + + The last three properties are useful in conjuction with the + vnfMgmt bridge type. They allow the user to map the + internal VNF management port to an external port, useful for VNF + configuration from WAN. + + In the previous example, the internal TCP port 443 (HTTPS) was + mapped to the external port 60001, which allows the user to access the + VNF management port from a web browser e.g. + https://<WAN_IP>:60001. + +
+
+ +
+ Instantiating a VNF + + When a VNF is onboarded and available in the VNF catalog, it can be + instantiated on connected uCPE devices. The configurations provided when + the VNF is onboarded, serve as a template for instantiation. Before + instantiating any VNF, please make sure the available storage space on the + uCPE device is big enough to accommodate the VNF you need to + instantiate. + + Follow the instructions below to instantiate a VNF: + + + + Select from the top toolbar VNF -> + Instances + + + + Click the Add button. + + + + Fill out the following mandatory fields: + + + + Name: a descriptive name. + + + + VNF Type: a list of onboarded VNFs. + + + + uCPE Device: the uCPE device to instantiate the VNF + on. + + + + Networking Configuration: + + + + Connect each configured NIC with a bridge, SR-IOV or PCI + Passthrough. + + + + Set up each NIC with a driver method. + + + + + All configured NICs must be set up before instantiating a + VNF. Failure to do so will end in a failed instantiation. + + + + + + + Add VNF-specific configuration data by uploading a Cloud-Init + file (when the Cloud-Init is used). + + + + Add any VNF-specific files (e.g license files). + + + + Hit the Create button to deploy the VNF and + run it on the specified uCPE device. + + + + Selecting the VNF -> Events menu will show + that the VNF was created and a connection was established. +
+ +
+ Accessing the VNF console + + Once the VNF is deployed, the VNF console can be entered using SSH + and virsh commands. The VNF Console is a typical starting point for + determining a successful deployment and configuring a VNF beyond Day + Zero. + + + + SSH to the uCPE device from the Enea uCPE Manager + (Device->SSH) using: + + + + For normal connections: the Username + (default: root), the Password (default: no + password), the Port (default: 22) and the + Reverse ssh checkbox: unchecked. + + + + For reverse ssh connections: the Username + (default: root) and the Reverse ssh checkbox + checked. The port will be automatically choosen by the uCPE + Manager in the range defined in the System -> + Configuration -> Reverse SSH configuration panel. By + default, the start port will be 7000 and the + maximum number of ports allocated to all devices is 10. Only one + port per device is allowed. + + A SSH Tunnel between the uCPE Manager and the device will be + created: + + ssh -f -N -T -R < Port > :localhost:22 <uCPE Mgr user>@<uCPE MgrIP> + + The device must be connected to the uCPE Manager for the + tunnel to be created. On connection, a normal ssh connection will + be made: + + ssh -p <Port> <Username>@localhost + + + + + + In SSH: + + + + Use the virsh list command to list all + running VNFs and to determine the VNF's instance number. + + + + Use the virsh console <instance + number> command to enter the VNF-specific + console. + + + + +
+ \ No newline at end of file -- cgit v1.2.3-54-g00ecf