Upgrading NMIS to 8.6.0G

Overview

Upgrading NMIS to 8.6.0G is extremely simple: all you need to do is follow the guidance of the interactive installation script, which will perform all the necessary steps that are safely automatable. Since version 8.5.6G the installer also takes care of installing both operating system packages and CPAN perl packages that NMIS depends on.

Please note that the installer script does not unconditionally overwrite your existing models or configuration items for safety reasons. Instead it offers to run the Automatic Model Upgrade Tool for you; if the model upgrades cannot be performed automatically (e.g. due to local customizations) you should follow the (semi-manual) model upgrade procedure to gain the benefits of the newest models.

For your convenience the installer offers to save a compressed backup snapshot of your NMIS configuration in root's home directory, and a log of the actions that were performed is saved in install.log in the NMIS directory.

Upgrading without any (or limited) Internet Access

Some of our customers are running Opmantek applications without direct access to the Internet, which can make installations and upgrades quite  tedious when new pre-requisites are introduced. We have therefore prepared a document that describes all the common options for working around this problem. The installer also mentions this page if it detects missing pre-requisites but no Internet access.

RRD Migration

NMIS Versions 8.5.6G and newer recommend an updated and simplified directory structure for your RRD files, which is more robust and easier to deal with from an administrative perspective: all of a node's RRD database files are kept within the directory <nmisdir>/database/nodes/<nodename>. (In the past, a node's RRD files were spread across multiple directories; furthermore the directory names did include the node type, which can change under certain circumstances and which can cause all kinds of subtle inconsistencies.)

This new recommended structure is controlled by the settings in models/Common-database.nmis, and great care has been taken to make the migration from old to new layout safe and unproblematic.

NMIS 8.5.8G ships with the tool admin/migrate_rrd_locations.pl and the installer will offer to run it for you automatically. This tool takes care of moving any existing RRD files from old to new location, and merges a new Common-database.nmis with the other settings in your existing file (e.g. custom RRD period values). You can run the tool repeatedly; if there is nothing to migrate, then it'll show that and simply exit. There is a simulation mode for only seeing prospective changes without performing them, and the migration tool also creates a rollback script in /tmp which can be used to reverse a (partially or fully completed) RRD migration.

It is highly recommended that you let the installer perform the RRD migration on your behalf.

If you have custom models, then it is required to run the RRD migration tool because it also handles the addition of missing RRD entries.
In this situation it will likely complain about your custom RRD types  not being known in the new database layout. This is remedied by first comparing models/Common-database.nmis with the one in models-install (admin/diffconfigs.pl will be helpful), then adding your custom entries to models-install/Common-database.nmis and finally rerunning admin/migrate_rrd_locations.pl.

JSON Migration

As outlined in the Release Notes, using the JSON format  for (non-RRD) database files is now the default. When you upgrade to version 8.6.0 the installer will offer to perform the migration for you, and it is highly recommended that you let the installer perform the JSON migration on your behalf.

General Upgrade Procedure

Once you've unpacked the NMIS tarball you will see install.pl in the NMIS source directory. Running ./install.pl -h will show you what options it offers.

A simple invocation of ./install.pl will prompt you for a few bits of necessary information and confirmations, after which the tool will backup your current NMIS installation and then perform the upgrade or installation steps. 

Once the installer has finished its  work you will likely need to review your config and model files and determine whether there are any customizations that you need to merge with newer files from the NMIS tarball. NMIS live configuration files are in /usr/local/nmis8/conf, the updated material from the release is in /usr/local/nmis8/install; for models please see the page on Upgrading Models.

To simplify the comparison and merging process NMIS provides the helper program admin/diffconfigs.pl. As an example, to check your Config.nmis against the one included with a new NMIS release you would use the tool like this:

cd /usr/local/nmis8
./admin/diffconfigs.pl install/Config.nmis conf/Config.nmis

Comparing install/Config.nmis to conf/Config.nmis
Output format:

"Config Key Path:
-       Status in install/Config.nmis
+       Status in conf/Config.nmis"

/system/threshold_period-pkts_hc:
-       -15 minutes
+       -5 minutes
...possibly lots more changes...
Difference Summary:
        /authentication/auth_user_name_regex
        /system/threshold_period-interface
        /system/threshold_period-pkts
        /system/threshold_period-pkts_hc