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.

The updates and upgrade procedures are almost completely automatized and require manual interaction only for breaking changes–improvements that introduce changes that are not backward compatible with the installed software, and for the cluster reactivation.

Warning

It is suggested to always use the automatic procedure, as it takes care of all the tasks related to the upgrade.

This 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 upgrade procedure, namely, 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 Instance Upgrade Procedure from 4.20 to 4.21, Cluster Upgrade from 4.20 to 4.21, and Satellite Upgrade.

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.2 to 4.4.

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