From adb4c492888c3f9639e03b37dd8ab6178f8eb02a Mon Sep 17 00:00:00 2001 From: mrpa Date: Thu, 19 Nov 2020 19:30:08 +0100 Subject: Feedback comments from siha, lumc, dape. Change-Id: Ib05e0ec31d159b46d08ef13378677caf9f80632c Signed-off-by: mrpa --- .../doc/images/prep_execution.png | Bin 127191 -> 116871 bytes .../doc/installation_guide.xml | 459 ++++++++------- .../doc/log_collector.xml | 649 +++++++++++---------- .../doc/troubleshooting.xml | 13 +- .../doc/upgrade_ena.xml | 6 + 5 files changed, 577 insertions(+), 550 deletions(-) (limited to 'doc') 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 index b783076..5d5a355 100755 Binary files a/doc/book-enea-nfv-access-getting-started/doc/images/prep_execution.png 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/installation_guide.xml b/doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml index 19a3397..809213d 100644 --- a/doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml +++ b/doc/book-enea-nfv-access-getting-started/doc/installation_guide.xml @@ -38,9 +38,9 @@ - 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 Connecting to the GUI of the uCPE Manager for management and + configuration. Network access between the CentOS 7 server and the + laptop is required. Please see the manual @@ -110,7 +110,7 @@ TCP - Required for WEB UI Access. + Required for GUI Access. @@ -118,8 +118,7 @@ TCP - Required for WEB UI Access and Device - Connectivity. + Required for GUI Access and Device Connectivity. @@ -127,7 +126,8 @@ UDP - TBD.This needs to be updated + Required for the uCPE Manager High Availability + Configuration. @@ -172,10 +172,11 @@ 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=5701-5708/tcp sudo firewall-cmd --permanent --add-service=4334/tcp -sudo firewall-cmd -permanent -add-service=2021-2040/tcp -sudo firewall-cmd -reload +sudo firewall-cmd --permanent --add-service=2021-2040/tcp +sudo firewall-cmd --permanent --add-service=7000-7010/tcp +sudo firewall-cmd --reload
@@ -218,14 +219,10 @@ OpenJDK 64-Bit Server VM 18.9 (build 11.0.3+7-LTS, mixed mode, sharing) The following system variables need to point to the OpenJDK 11 installation: - export JAVA_HOME=$(dirname $(dirname $(readlink $(readlink $(which javac))))) + 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 @@ -238,7 +235,7 @@ export CLASSPATH=.:$JAVA_HOME/jre/lib:$JAVA_HOME/lib:$JAVA_HOME/lib/tools.jar

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.
+ any existing PostgreeSQL installation needs to be uninstalled. Uninstalling PostgreSQL @@ -292,7 +289,9 @@ userdel postgres
- Follow the installation process as described below. + Follow the installation instruction for the uCPE Manager + available in section add olink to section with ID + "install_ucpe_mg"
@@ -385,199 +384,211 @@ userdel postgres
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>. - + The uCPE Manager can be installed using as a fresh/first-time + configuration or using a backup file of a previous installation, created + within the uCPE Manager GUI. - - 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. +
+ Fresh Installation of the uCPE Manager - 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. - + On the CentOS 7 server open a terminal, log into a bash shell + with the root account and perform the following: - - Install the uCPE Manager as a service with the name - ucpemanager. - + + + Unzip + Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz - - Start the ucpemanager service - - - + The directory in which the archive has been unpacked will be + denoted as: <uCPEM-installdir>. + - - 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. - - + + Enter <uCPEM-installdir>. + - - 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. - + + 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. + - 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. + + Run the following interactive command: - - 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? - + ./install.sh /opt/ems \ +Enea_NFV_Access_uCPEManager_<version>-build<build_number>.tar.gz - To install the uCPE Manager with the restore option provide an - additional argument as shown below during installation: + 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 + + + - ./install.sh \ + + 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. + +
+ +
+ Installation of the uCPE Manager using a Back-up file + + 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) is + different from the uCPE Manager snapshot obtained during a uCPE + Manager Upgrade or Uninstall operation + (ucpemanager-Backup-YYYYddMMHHmm.tar.gz) needed + for recovery of the uCPE Manager.add olink to section with + id "restore_prev_ucpe_install" + + + 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 +
@@ -721,43 +732,41 @@ of=/dev/sdb bs=4M conv=fsync - The Layer 3 configuration of WAN Interface(s). - - - - The Static or Dynamic IP. + The Management Interface. The network interface used by + the uCPE Manager to communicate with the uCPE device. 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. + configuration. The user needs to connect the same number of + cables as the number of WAN ports that he wishes to configure + (DHCP is the default setting). 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. + 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. + The Layer 3 configuration of WAN Interface(s). + + + + The Static or Dynamic IP. 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. + Web-installer, NFV Access is installed on the hard drive (the largest + drive found on the uCPE device will be used for installation. Now the + user must remove USB stick and reboot the device.
@@ -787,11 +796,6 @@ of=/dev/sdb bs=4M conv=fsync device WAN port. - - One uCPE device LAN connected to the laptop using an ethernet - cable. - - The USB is removed from the uCPE device. @@ -845,7 +849,7 @@ of=/dev/sdb bs=4M conv=fsync To create an offline - configuration + configuration In a browser access the uCPE Manager, then Applications->Offline @@ -859,9 +863,10 @@ of=/dev/sdb bs=4M conv=fsync 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 + string identifying the configuration. The + deviceVersion must match the Enea NFV Access + version of the uCPE device and the deviceId + must be the previously set identifier of the uCPE device (uCPE Identifier). @@ -932,10 +937,10 @@ of=/dev/sdb bs=4M conv=fsync 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. + user should remove all WAN cables, reinsert the USB stick, reconnect + the laptop using the ethernet cable, reboot the uCPE device and then + access the Web-installer + (http://172.16.1.1). When a uCPE device is registered it can be manually added to the 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 index 410e692..95a8fa9 100644 --- a/doc/book-enea-nfv-access-getting-started/doc/log_collector.xml +++ b/doc/book-enea-nfv-access-getting-started/doc/log_collector.xml @@ -11,355 +11,364 @@ 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: + GUI. - - - Access Operations -> Collect - Debug Logs. - +
+ Collecting the Logs - - Provide a file name in the new window. - + 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: - - Press the Execute button. + + + Access Operations -> Collect + Debug Logs. + - 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. - + + Provide a file name in the new window. + -
- 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 - - - - - - -
-
-
+ + Press the Execute button. -
- 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. + 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. +
- Device File Listing Table + Collecting Debug Logs + fileref="images/collect_debug_logs.png" />
- -
- - - 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. + + 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.
- Downloaded Files Table + Collecting Debug Logs + fileref="images/fault_events.png" />
-
- -
- -
- 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. - + +
+ +
+ 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. + + - - 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. - - +
+ Device File Management - - Deleting the logs file from the uCPE Manager does not affect the - file located on the uCPE device. - -
+ + + + + + +
+ +
+ 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 + + -
- 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 - - - - - - -
-
+
+ Debug Settings -
- 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 - - - - - - -
+ + + + + +
+
diff --git a/doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml b/doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml index b3173e6..fc2350a 100644 --- a/doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml +++ b/doc/book-enea-nfv-access-getting-started/doc/troubleshooting.xml @@ -90,14 +90,14 @@ - Cleanup the current upgrade attempt with: + 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 + previous uCPE Manager configuration as described in olink to the section/chapter describing: Installing with the restore option. @@ -117,7 +117,14 @@ Use the Reconnect button from the - uCPE Manager's WEB-UI. + uCPE Manager's GUI. + + + + Connect to uCPE Device console and run the factory reset + script: + + /usr/local/odm/bin/factory_reset.sh 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 index 4b1a7dc..23d2f1d 100644 --- a/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml +++ b/doc/book-enea-nfv-access-getting-started/doc/upgrade_ena.xml @@ -9,6 +9,12 @@
Upgrading the uCPE Manager + + It is recommended to create a system backup, by accessing from the + uCPE Manager GUI: System -> System + Backup for recovery in case of an upgrade failure. + + Unzip the -- cgit v1.2.3-54-g00ecf