User Guide

Before you start

This section contains useful information and suggestions to guide you in the process of successfully update and upgrade your NetEye Single Node or Cluster installation.

Upgrade to NetEye 4.23 release represents a milestone in development and consists of an OS upgrade and migration: in this sense, the upgrade procedure is unique and different from all the previous. While most of the procedure is automatic, manual interaction is required to reboot NetEye and if on the NEtEye installation features customizations or specific kernel modules.

Operating system migration

From version 4.23 onwards, NetEye will be based on RHEL 8. For this reason the upgrade to this version includes a migration from CentOS 7 to RHEL 8, with an intermediate upgrade step to RHEL 7. Most of this procedure is automatic, with only a few manual steps required.

Important points:

  1. 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.

  2. 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 is found, refer to the related troubleshooting section for directions on how to proceed.

  3. There will be a downtime that will last for the whole procedure

  4. Make sure you have a backup of your system before starting the conversion.

The NetEye Update & Upgrade section is organised in multiple parts: First of all, this page contains a number of useful information about supporting tasks that need to be carried out as part of the whole Update & Upgrade procedure, especially before starting the procedure: learn about Safe Command Execution, how to migrate RPM configuration files, read the Release Notes, and How to Obtain the Changelog

The update process for Single Node, Cluster, and Satellite follows, see Update Procedure and its subsections.

Then the heart of the upgrade process can be found in the dedicated sections: Single Node Upgrade from 4.22 to 4.23, Cluster Upgrade from 4.22 to 4.23, and Satellite Upgrade from 4.22 to 4.23.

Finally, a Troubleshooting section helps you in tackling the problems than may arise during the update and upgrade procedures.

Overview

It is important to regularly update and upgrade your NetEye system in order to reduce security risks and ensure the latest bugfixes are applied.

If you want to upgrade NetEye and have past experience doing so, you can skip directly to the section for upgrading from your current version (the section titled “Upgrade from 4.X to 4.Y” in the index at the left). You MUST upgrade sequentially from one version to the next: do NOT skip versions, for instance going from 4.20 to 4.22.

Because NetEye adheres to the Semantic Versioning Initiative, the software we produce will always fall into one of the following two categories:

  • Updates: A set of minor changes, for instance bug fixes or clarifications to the documentation, which do not introduce new features or change expected behavior. Updates can be released weekly, or even daily, as the need arises.

  • Upgrades: The introduction of new or significantly changed features, creating new interfaces, APIs and behaviors. Upgrades are planned in advance on a two-month release schedule, and are announced at the NetEye Blog.

Safe Command Execution

When running update commands, we recommend that you keep a log of the commands and outputs. One way to do this is to increase the number of lines of shell history in your terminal (e.g., in Putty, these settings are found in the “Window” options section).

Another way is to run the update command in a detached bash session by making use of the nohup command to append all output to a local log file. In this example, the update command runs in the background with all output written to nohup.out:

# nohup yum update arg1 arg2 --enablerepo=neteye -y &

[1] 9145
nohup: ignoring input and appending output to `nohup.out`

The nohup command proves useful whenever a command that may take long time to execute must be issued on a remote server. Indeed, if for any reasons the connection drops, the command will continue and its log saved on a file, allowing to check its output as soon as the connection is reinstated.

Hint

You should always use the nohup command when running neteye update, neteye upgrade and neteye_secure_install, as they are time consuming tasks.

Using nohup while backgrounding the process with a trailing & has the additional advantage that if your connection is unreliable, for instance if you are at a remote site or connecting via a VPN, then the update process will not crash and become corrupted.

If you use nohup, you can follow the update process by examining the output file at any time:

# tail --retry -f nohup.out

For more information, please refer to the official nohup(1) documentation.

Migrate .rpmsave and .rpmnew Files

Each upgraded package can potentially create .rpmsave and/or .rpmnew files. You will need to verify and migrate all such files.

You can find more detailed information about what those files are and why they are generated in the official RPM documentation.

Briefly, if a configuration file has changed since the last version, and the configuration file was edited since the last version, then the package manager will do one of these two things:

  • If the new system configuration file should replace the edited version, it will save the old edited version as an .rpmsave file and install the new system configuration file.

  • If the new system configuration file should not replace the edited version, it will leave the edited version alone and save the new system configuration file as an .rpmnew file.

Note

You can use the following commands to locate .rpmsave and .rpmnew files:

# updatedb
# locate *.rpmsave*
# locate *.rpmnew*

The instructions below will show you how to keep your customized operating system configurations.

How to Migrate an .rpmnew Configuration File

The update process creates an .rpmnew file if a configuration file has changed since the last version so that customized settings are not replaced automatically. Those customizations need to be migrated into the new .rpmnew configuration file in order to activate the new configuration settings from the new package, while maintaining the previous customized settings. The following procedure uses Elasticsearch as an example.

First, run a diff between the original file and the .rpmnew file:

# diff -uN /etc/sysconfig/elasticsearch /etc/sysconfig/elasticsearch.rpmnew

OR

# vimdiff /etc/sysconfig/elasticsearch /etc/sysconfig/elasticsearch.rpmnew

Copy all custom settings from the original into the .rpmnew file. Then create a backup of the original file:

# cp /etc/sysconfig/elasticsearch /etc/sysconfig/elasticsearch.01012018.bak

And then substitute the original file with the .rpmnew:

# mv /etc/sysconfig/elasticsearch.rpmnew /etc/sysconfig/elasticsearch

How to Migrate an .rpmsave Configuration File

The update process creates an .rpmsave file if a configuration file has been changed in the past and the updater has automatically replaced customized settings to activate new configurations immediately. In order to preserve your customizations from the previous version, you will need to migrate those from the original .rpmsave into the new configuration file.

Run a diff between the new file and the .rpmsave file:

# diff -uN /etc/sysconfig/elasticsearch.rpmsave /etc/sysconfig/elasticsearch

OR

# vimdiff /etc/sysconfig/elasticsearch.rpmsave /etc/sysconfig/elasticsearch

Copy all custom settings from the .rpmsave into the new configuration file, and preserve the original .rpmsave file under a different name:

# mv /etc/sysconfig/elasticsearch.rpmsave /etc/sysconfig/elasticsearch.01012018.bak

Release Notes

You can find the full release notes on our blog via the following link: NetEye Release Notes.

How to Obtain the Changelog

From version 4.6 onwards, the changelog can be created automatically, on-demand. You can generate the changelog of the current release at any time by following these steps.

First, install the changelog plugin for yum:

# yum install yum-plugin-changelog -y

You can then view the changelog by passing the last release date to the plugin, which will show all changes since that date. For instance, for NetEye 4.8:

# yum changelog 2019-07-31 all > changelog.txt

Proxy Configuration

If your NetEye Node does not have direct connection to Internet and passes through an HTTP proxy instead, you need to perform certain operations to ensure that all software (e.g. DNF, Subscription Manager) will pass through your proxy during (and after) the upgrade procedure to NetEye 4.23.

To configure the proxy, follow these directions:

  1. Configure the environment variables

  2. Add the proxy configuration in the file /etc/yum.conf if it is not configured yet. For example, if your proxy uses proxy.example.com hostname, listens on port 12345 and enforces basic authentication with username myuser and password mypassword, the file /etc/yum.conf should look like the following:

    [main]
gpgcheck=1
installonly_limit=3
clean_requirements_on_remove=True
best=True
skip_if_unavailable=False
proxy="http://proxy.example.com:12345"
proxy_username="myuser"
proxy_password="mypassword"

  3. Add the proxy configuration for DNF as follows (this lets DNF, once installed during the upgrade, immediately use the proxy configuration):

    1. Create the directory /etc/dnf/ by executing:

      neteye# mkdir "/etc/dnf/"

    2. Copy the YUM configuration file to /etc/dnf/dnf.conf by executing:

      neteye# cp -p "/etc/yum.conf" "/etc/dnf/dnf.conf"

      Note

      During the upgrade process the /etc/yum.conf file will be replaced with a symbolic link to /etc/dnf/dnf.conf. This will cause the creation of a /etc/yum.conf.rpmnew and an /etc/yum.conf.rpmsave file. These files can be safely removed without doing any migration.

  4. Configure Leapp repositories to use the proxy. The repositories configuration is located in /etc/leapp/files/leapp_upgrade_repositories.repo. The procedure is to add the proxy directive in every repository definition, except for the local one, i.e. rhel8-rpms-migration. An example of a repository definition with the proxy configuration is the following:

    [neteye-rhel8]
name=NetEye
baseurl=https://repo.wuerth-phoenix.com/rhel8/neteye-4.23
gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-NETEYE
enabled=1
priority=1
proxy=http://myuser:mypassword@proxy.example.com:12345

  5. Add the proxy configuration for the Subscription Manager. The convert2rhel utility will install it and use it during the conversion.

    1. Create the Subscription Manager configuration folder:

      neteye# mkdir "/etc/rhsm/"

    2. Copy the sample file to the final location:

      neteye# cp "/usr/share/neteye/setup/rhsm.conf.sample" "/etc/rhsm/rhsm.conf"

    3. Edit the /etc/rhsm/rhsm.conf file to add the proxy configuration. Search for the following keys and set the respective settings:

      • proxy_hostname

      • proxy_scheme

      • proxy_port

      • proxy_user (only if the proxy is protected by authentication)

      • proxy_password (only if the proxy is protected by authentication)