Overview
You have just upgraded to NMIS 8.5.6G and the installer has listed lots of differencese 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.
- Compare the new
models-install
and the activemodels
.
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. - 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". - 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 blanketcd /usr/local/nmis8; cp -fav models-install/* models/
and you're done. - 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.
Thediffconfigs.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.