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 installation, either single node or cluster.

This section is organised in four 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 process, namely:

Then, the update process is introduced for both single node and cluster (see Updating CentOS and NetEye and its subsections),

Finally, the heart of the upgrade process can be found in the two dedicated sections: Upgrade from 4.19 to 4.20 and Cluster Upgrade from 4.19 to 4.20.

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

The NetEye Secure Install Script

The secure install procedure, implemented within the neteye_secure_install script, is used after every installation, upgrade or update to:

  • Reconfigure NetEye services and/or migrate configurations and databases after important changes

  • Restart services that were stopped or modified

  • Create certificates for secure communication

Before making any changes, the secure install script will also run a subset of light and deep health checks to ensure that NetEye will not be adversely affected due to a transient problem like low disk space or custom configurations. Note that this should not replace running a separate, manual deep health check both before and after you upgrade or update.

The script should be run immediately after the installation or update of any new RPM packages from NetEye repositories. To run it, just type in the name of the script in a shell as root:

# neteye_secure_install

Finalize the NetEye Upgrade

Once all the steps in the upgrade procedure have been carried out, you should finalize them. The following command will apply the necessary changes to your NetEye installation:

# nohup neteye_secure_install

Next, start any potentially stopped and/or newly installed NetEye services:

# neteye start

Complete the upgrade process by launching the following script:

# 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 our service and support team to evaluate the best way forward for upgrading your NetEye system.