Overview

You have just upgraded to NMIS 8.5.6G and the installer has listed lots of differences between the (live) models/ directory and the new data in models-install/. Naturally want your NMIS installation to perform perfectly and wish to benefit from the continual improvements that we make to NMIS (which includes using the newest models).

This document describes how such model upgrades should be handled.

The  Upgrade Process

NMIS ships with new models in models-install/, and (with the exception of RRD structure migration special case in 8.5.6G), the installer never makes any changes to your live models/ directory. This is because you may have created complex custom models for your installation or adjusted the standard models, both of which the installer simply mustn't overwrite or damage. The installer errs on the side of caution, therefore some manual checks and merging are required.

1. Compare the new models-install and the active models.
   Since NMIS 8.5.6G the installer performs that step for you, and leaves a comprehensive listing of the differences in a file in /tmp. See the section on Tools and Helpers below for details.
2. Copy over any new files from models-install.
   A simple "cd /usr/local/nmis; cp -nav models-install/* models/" will copy any new files over (and print a line for each file that was copied). The "-n" is a crucial argument, meaning "don't  overwrite existing files".
3. Replace existing files with new ones if the differences are not caused by your local modifications.
   After consulting the list of differences, you conclude that the differences in question are not caused by local modifications; In that case you'd simply use "cp -fav .... " to copy the specific file from models-install/ to models/.
   If you haven't made any model changes at all, then you can do a blanket cd /usr/local/nmis8; cp -fav models-install/* models/ and you're done.
4. Merge any remaining local changes with new model files.
   If differences related to deliberate local changes remain, then you will have to use an editor to manually modify the model files in question to bring in new material.
   This can be a laborious process, and in all likelihood you will have to consult the documentation on NMIS modelling and the NMIS training material.
   The diffconfigs.pl tool will be (repeatedly) useful  to see if any todo's are left, and it is advisable that you run "perl -c <modelfile.nmis>" to syntax-check your final merged file.

Types of files in models and models-install

The models directory contains four types of files, which differ in the likelihood of local changes:

• Common-X.nmis
  Common-database commonly has local adjustments if you want different RRD data retaining periods, or use a non-standard RRD directory schema.
  Common-thresholds is another likely candidate for local changes. Most of the other Common-X files rarely require local adjustments.
• Model.nmis
  This file controls the model autodetection. If you haven't created custom models and added them to the model autodetection, then this file will not contain local changes.
• Model-Y.nmis
  These files constitute the modelling configuration for all device types that NMIS knows about. Local changes  would be present if you extended or adjusted existing models in-place.
• Graph-Z.nmis
  These files contain the graph definitions for NMIS's graphs. Local modifications are possible but not especially likely.

Tools and Helpers

compare_models

This tool performs a bulk comparison of all files in two models directories (usually models/ and models-install/). NMIS 8.5.6G and above ship with this tool as admin/compare_models.pl, and the installer will automatically invoke it for you.

The output will be similar to this example:

./admin/compare_models.pl models models-install 
Performing model difference check, please wait...
......................................................................
The comparison tool has detected some differences
between the old models (in models) and 
the new models (in models-install). 
The affected files are:
Common-database.nmis Common-heading.nmis Common-stats.nmis
Common-threshold.nmis Graph-QualityOfServiceStat.nmis Graph-SignalErrors.nmis
Graph-SignalLevel.nmis Graph-abits.nmis Graph-fan-status.nmis

A detailed listing of these differences has been 
saved in /tmp/model-diffs-2015-02-12.
You should review those differences (using less or an editor like 
nano, vi or emacs) and merge the model files where applicable.

The detailed listing is left in /tmp/model-diffs-<currentdate>, and contains a block of text for each file that was checked.  The actual comparison is performed by diffconfigs.pl, which is described below.

diffconfigs

The tool admin/diffconfigs.pl has been part of NMIS for quite some time. Its name implies that it compares configuration files, but it's flexible enough to also take care of models files.

It is invoked like this: ./admin/diffconfigs.pl somedir/oneconfig.nmis somedir/otherconfig.nmis and produces a list of differences similar to the following example:

./admin/diffconfigs.pl models/Model-CiscoNXOS.nmis  models-install/
Comparing models/Model-CiscoNXOS.nmis to models-install//Model-CiscoNXOS.nmis
Output format:
"Config Key Path:
-       Status in models/Model-CiscoNXOS.nmis
+       Status in models-install//Model-CiscoNXOS.nmis"
/systemHealth/sys/cdp:
-       <NOT PRESENT>
+       <DEEP STRUCTURE>
/systemHealth/sections:
-       env_temp
+       cdp,env_temp
Difference Summary:
        /systemHealth/sections
        /systemHealth/sys/cdp

A quick explanation of the format of the output:

• The individual differences are shown with the path-like "location" of the  item in question, followed by two lines of difference info.
• The line prefixed "-" describes the status in the first file, and the line with "+" describes the other.
• If the difference is textual (like for systemHealth/sections in the example) then you will see the texts in question.
• If the difference is structural (like for systemHealth/sys/cdp), then you will likely see descriptions like "NOT PRESENT".  If the structural types don't match you'll see info like "DEEP STRUCTURE, sometype".
• If a structure is totally missing in one file, then no differences will be reported for its sub-elements - only the missing structure is indicated. This means that it's advisable to re-run diffconfigs after adding any structural items.
• At the very end there's a summary of the differences, only listing the logical "locations" where differences were encountered.
• Finally, the exit code of the command  is 0 if there were no differences, 1 if there were differences, and usually 255 if the operation failed altogether.

Note that if the file names of the files to compare are identical and only the directories differ, then you can call diffconfigs like this: ./admin/diffconfigs.pl somedir/oneconfig.nmis otherdir/ and it'll find the appropriate second file to compare.