Satellite Upgrade from 4.22 to 4.23¶

This guide will lead you through the steps specific for upgrading a NetEye Satellite installation from version 4.22 to 4.23. You must have successfully completed the Satellite Update Procedure before attempting to start the upgrade procedure.

Warning

Remember that you must upgrade sequentially without skipping versions, therefore an upgrade to 4.23 is possible only from 4.22; for example, if you have version 4.14, you must first upgrade to the 4.15, then 4.16, and so on.

Before starting an upgrade, you should very carefully read the latest release notes on NetEye’s blog and check the feature changes and deprecations specific to the version being upgraded. You should check also the whole section Breaking Changes below.

The remainder of this section is organised as follows. Section Breaking Changes introduces substantial changes that users must be aware of before starting the upgrade procedure and may require to carry out some tasks before starting the upgrade; then section NetEye Satellite Upgrade Procedure presents the actual procedure.

Breaking Changes¶

New underlying operating system

We recall that the upgrade procedure includes a change of operating system. Therefore, the upgrade consists of 3 steps:

Conversion from CentOS 7 to RHEL 7
Upgrade from RHEL 7 to RHEL 8
NetEye upgrade finalization

A manual reboot of the system is required between each step. The 3-steps procedure can take a long time and must be performed in its entirety in one session, as systems in intermediate state are not supported.

Warning

There will be a downtime for the duration of the procedure until its completion and all NetEye services will be stopped during this period.

NetEye Satellite Upgrade Procedure¶

Prerequisites¶

Be sure to meet the following requirements before starting:

NetEye Master must be version 4.23 fully updated
NetEye Satellite must be version 4.22 fully updated
The 4.23 NetEye Satellite configuration archive is present in the path /root/satellite-setup/config/4.23/satellite-config.tar.gz. To generate and send the Satellite configuration archive see the section Satellite Configuration
NetEye Satellite must be up and running with no health checks failing
There must be at least 20GB of free space in /
There must be at least 20GB of free space in /var
All nodes must be able to reach the following domains over HTTPS (port 443 TCP):
- cdn.redhat.com
- cdn-ubi.redhat.com
- cert-api.access.redhat.com
- cert.cloud.redhat.com
- subscription.rhsm.redhat.com
You need an organization ID, an activation key and a name (see below) before attempting the upgrade. To obtain them, please refer to the official channels: sales, consultant or support portal.
Kernel requirements:
- Some kernel modules are incompatible with RHEL 8 and need to be replaced. The system upgrade command will ensure those modules are not active in your installation. However, if any are found, refer to the related troubleshooting section for directions on how to proceed.
- Ensure the system is running the latest installed kernel. To check this please compare rpm -q kernel with uname -r.
- Only one unused kernel version should be installed on the system (this is needed to avoid filling the boot partition during the upgrade). To remove all kernels except the currently running version and the previous one you can use the command:
```
neteye# package-cleanup --oldkernels --count=1
```
Filesystem types requirements:
- Ensure there are no XFS filesystems with ftype=0 mounted.
  
  Run the script:
```
neteye# for dev in $(findmnt -t xfs -n -o SOURCE); do echo "$dev: $(xfs_info $dev | grep -w -o ftype=0)"; done
```
  Case 1: If no output is reported, then no XFS filesystems with ftype=0 are mounted.
  
  Case 2: If any output is reported, as in the snippet below, then please refer to XFS ftype=0 case.
```
/dev/mapper/rhel-root: ftype=0
/dev/mapper/rhel-usr: ftype=0
/dev/vda1: ftype=0
/dev/mapper/rhel-home: ftype=0
/dev/mapper/rhel-var: ftype=0
```
- Ensure no Network filesystems (e.g. NFS, SMB, GlusterFS) are mounted or configured to be mounted on reboot. Otherwise please refer to the support portal for assistance.
Package installation requirements:
- Ensure there are no unfinished YUM transactions. For that please run the following command:
  neteye# yum-complete-transaction --cleanup-only
- Ensure no duplicate RPM packages are installed. To check if there are any duplicates you can execute:
  neteye# package-cleanup --dupes
  To remove any discovered duplicates run instead:
  neteye# package-cleanup --cleandupes
- Ensure urllib3 and requests python modules are only installed via RPM packages. In case urllib3 and requests are installed via pip, please run the following commands:
  neteye# pip2 uninstall requests urllib3
  neteye# yum reinstall python-urllib3.noarch python-requests.noarch
Ensure that there are no customizations or recurring tasks running as they may interfere with the upgrade. This includes for example backups, Beats, custom scripts and so on.

If your NetEye Satellite installation uses some custom services or some custom Icinga2 checks, it is possible that you will need to fix them manually during or after the upgrade and you may need the assistance of our support or consultant team.

Step 1: Conversion from CentOS 7 to RHEL 7¶

To perform the conversion to RHEL 7, run from the command line the command:

sat# (nohup neteye node system-upgrade --org <organization_id> --key <activation_key> --name <name> &) && tail --retry -f nohup.out

This command takes care of checking the system status and performs the conversion to RHEL 7. We recall that the organization ID and the activation key can be obtained upon request to our service desk.

In case of any errors, the command will show the reason of the failure. After fixing the problem, please repeat Step 1 from the beginning.

At the end of the conversion a success message is shown and you will be prompted to restart the system. To reboot the system run the following command:

sat# reboot

Step 2: Upgrade from RHEL 7 to RHEL 8¶

After the previous reboot, it is time to upgrade from RHEL 7 to RHEL 8 by running command:

sat# (nohup neteye node system-upgrade --org <organization_id> --key <activation_key> --name <name> &) && tail --retry -f nohup.out

During the upgrade the following kernel modules will be removed because they are not compatible with RHEL 8:

pata_acpi: pata_acpi is used for device configuration and power management of P-ATA storage devices
pam_pkcs11: this Linux-PAM login module allows a X.509 certificate based user login

The command will perform a pre-upgrade in order to check the status of the system; any of the following conditions may prompt a manual intervention:

Since a newer kernel version is installed but currently not running, it is necessary to reboot the system, then execute the neteye node system-upgrade command again
Some packages not provided by NetEye have been installed and are not compatible with RHEL 8: packages that are not compatible with RHEL 8 must be removed or can be updated by saving a RHEL 8 compatible update package in the folder /var/www/html/rhel8-rpms-migration. Alternatively, additional repositories to be used only during the upgrade can be added to file /etc/leapp/files/leapp_upgrade_repositories.repo.
Other system-specific cases: in this case a detailed report of the causes will be generated in /var/log/leapp/leapp-report.txt

In case of any errors, the command will show the reason of the failure. After fixing the problem, please repeat Step 2 from the beginning.

At the end of the upgrade a success message is shown and you will be informed to restart the system. During the reboot further tasks will be performed in order to complete the upgrade to RHEL 8.

Warning

The whole reboot procedure will take at least 35-40 minutes.

To reboot the system run the following command:

sat# reboot

Step 3: OS Upgrade finalization¶

To complete the procedure and finalize the OS upgrade, run from the command line the command:

sat# (nohup neteye node system-upgrade --org <organization_id> --key <activation_key> --name <name> &) && tail --retry -f nohup.out

More information on this command can be found in section neteye node system-upgrade; a dedicated section provides directions in case the command fails.

Post-upgrade Tasks¶

A few tasks are needed on the satellite:

Please check for any .rpmnew and .rpmsave files (see the Migrate RPM Configuration section for further information).
Execute the command below to setup the new version of the NetEye Satellite:
```
sat# neteye satellite setup
```
Launch the following script:
```
sat# neteye_finalize_installation
```

Note

You should launch the finalize command only if all previous steps have been completed successfully. If you encounter any errors or problems during the upgrade process, please contact our service and support team to evaluate the best way forward for upgrading your NetEye System.