Table of Contents

Overview

A substantial proportion of NMIS' functionality is provided by the device model and graph files, and using the newest model files is vital to ensure that your NMIS installation performs perfectly and benefits from the continual improvements that we make to NMIS. It is therefore very important to keep your model and graph files uptodate and in sync when you upgrade to a new NMIS version, but this can be a bit of a challenge as these are user-customisable and -extensible.

This document describes the new capabilities and limitations of the new automatic model upgrade tool (which ships with NMIS from 8.5.12G onwards, but can be downloaded from this page as well). For situations that exceed the automatic upgrader's capabilities, the recommended procedure for manual  model upgrades is also described.

The Automatic Model Upgrader

From version 8.5.12G onwards NMIS ships with a model upgrade tool and the installer offers to run it for you. If you are using NMIS 8.5.10G you can download the upgrade tool here; it is recommended that you save it as /usr/local/nmis8/admin/model_upgrade.pl.

Please note that the model upgrade tool is version-specific and will not work with NMIS releases other than the one it was shipped with. The current version for 8.5.10G handles model upgrades from any 8.5.X and 8.4.X versions to 8.5.10G.

Test Mode

Simply starting the tool without arguments will present a brief help text:

$ ./admin/upgrade_models.pl 
Usage: upgrade_models.pl [-u] [-o|-p] [-n regex] <new model dir> <live model dir>
-u: do perform the upgrade instead of just reporting model file states
-o: report only upgradeable files
-p: report only problematic files
-n: NEVER upgrade the matching files
...

The tool must be given the paths to the new models, i.e. /usr/local/nmis8/models-install and the "live" models, i.e. /usr/local/nmis8/models. It will not work if you give the directory paths in the wrong order.
If run without further arguments it will analyze the live models and determine which can be upgraded. It will NOT make any changes, but only print a line of status information for every model and graph file it operates on. Here is an example, upgrading from 8.5.2G (with custom extras) to 8.5.10G:

$ ./admin/upgrade_models.pl models-install models
Common-calls.nmis is uptodate.
...
Common-database.nmis is upgradeable: not modified since installation.
...
Common-Cisco-asset.nmis is upgradeable: new file.
Model-customhw.nmis is NOT UPGRADEABLE: locally created custom file.
Model-net-snmp.nmis is NOT UPGRADEABLE: has been modified since installation.

If you want to be informed of upgradable files only, you can add the option -o. If you want to see only files that can not be upgraded, use option -p.

Upgrade Mode

The upgrade tool will upgrade your model and graph files if and only if you run it with option -u (which can be combined with -o or -p). The output is the same as in test mode, except that as final step the actual changes will be made and the tool will report "Upgrading all upgradeable model files...Completed."

If desired you can also exclude certain model or graph files from the upgrade, using the -n option (which expects a regular expression argument, like "-n Model-custom").

Limitations

• The upgrade tool compares the model file states against an embedded list of older releases and cannot upgrade models that are older than these known releases.
  For version 8.5.10G the upgrade tool was primed with states for releases 8.4.X and 8.5.X.
• The upgrade tool will identify a file as 'locally modified' if you make any changes to it, and will not overwrite it under any circumstances.
  Changing a text field like '42' to the number 42 is considered a change. Adding white space outside of a string is not detected as change.
  Changing comments is not a change, nor is reordering items in a hash structure.
  All "locally modified" files will be left as-is by the upgrade tool.
• The upgrade tool requires a complete and uptodate directory of "new" models.
  If you modify files in models-install the tool will refuse to work with these because of the state that is inconsistent with its embedded knowledge.
• The upgrade tool is version specific and cannot  upgrade your models to any version but the one it was primed for and shipped with.
  I.e. the current tool targetting version 8.5.10G will be of no use to you if you want to upgrade to an older version of NMIS.

The Manual

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.

...

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 installer does not make any changes to your live models/ directory unless directed to by you during the upgrade. 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 (and the upgrade_models tool) err on the side of caution, therefore some manual checks and merging are required if you  have local model customisations.

1. Use upgrade_models.pl where possible.
2. 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.
3. 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".
4. 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.
5. 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.

...