Upgrade Guide: 1.12 to 1.14

From OpenNMS
Jump to: navigation, search

OpenNMS 14 is the latest major stable release, it has completely new topology representation and major improvements for geographical maps. You can find all changes in the What's New section.


In this document, $OPENNMS_HOME refers to the root of the OpenNMS installation. Usually, this is /opt/opennms, or on Debian systems, /usr/share/opennms.

It is helpful to create this environment variable as is correct for your installation to allow for cutting-and-pasting in commands below.

# RedHat-type systems

# Debian/Ubuntu systems

# verify the path setting

Upgrades from Older Releases

Note that if you are upgrading from OpenNMS 1.10, it is STRONGLY recommended you upgrade to the latest 1.12 release before upgrading to 14. For RPM, you can do so through the "obsolete" repository, and on Debian, the "oldstable" repository.

Backup OpenNMS 1.12.9

You should do this before any upgrade, of course, but it's doubly important on major version upgrades, where configuration can change more significantly.

New Requirements

Java 1.7u71 or later

While we have been recommending JDK 1.6 for a while for performance reasons, OpenNMS 14 now requires JDK 1.7u71 or higher to avoid several critical bugs in older versions of the JDK. We have better feedback with Oracle Java 7 in production environments. We also have users running OpenJDK 7 without issues. We give our best to support both.

  • check the Java version to ensure Java 7 update 71 or later is installed
java -version

Preparing Your Configuration Files for Upgrade

Comparing Your Changes

Most recent releases of OpenNMS include a pristine copy of the configuration files that were first installed, to compare against for the purposes of upgrading. If you want to see how your configuration files compare to them, you can run:

diff -Nurdbw $OPENNMS_HOME/share/etc-pristine $OPENNMS_HOME/etc

It gives you an overview how you customized your configuration.

On Debian/Ubuntu systems, run:

diff -Nurdbw $OPENNMS_HOME/etc-pristine /etc/opennms

The diff option --brief can be added to just show the modified file names.

Separated graph definitions

If you have customized graphs, be aware to put this changes in a customized properties file and drop them in the snmp-graph.properties.d directory. If you overwrite existing graphs, you can use the suppress directive in your graph definition file. For example


This will prevent the default mib2.bits report to be displayed in the WebUI. So you don't have to change the default graph definition file which makes your next update easier.

Jasper Reports

If you modified any of the jasper reports introduced late in the 1.8 series, note that they got cleaned up quite a bit in 1.12. Keep that in mind while merging configuration conflicts.

If you customized any of the subreport definitions that came with OpenNMS 1.12, you may need to update these *.jrxml files.

Datacollection Configuration

This is only related to SNMP datacollection. If you made any changes to the datacollection folder, you will want to make a note of them, and apply them to the relevant individual file(s) in $OPENNMS_HOME/etc/datacollection/. If you create new datacollection files, note that you'll need to add an <include-collection /> reference in datacollection-config.xml.

As of OpenNMS 1.12.9, the OpenNMS installer script will remove these attributes. This procedure should be done as per below.


Now you are ready to upgrade!

Before actually performing the upgrade, you may want to take a look at the Managing Configuration Changes with Git page for a nice way to use git to make configuration upgrades easier.

For a refresher on installation and upgrade, see the Upgrading page.

If you have problems, don't forget to ask questions on the mailing lists or IRC.

Upgrade (part 1): Upgrade binaries

The first step is to upgrade the OpenNMS binaries.

  • Debian/Ubuntu example
aptitude update
aptitude upgrade

As OpenNMS packages are installed, you will be prompted to either replace or leave alone customized configuration files. One can either accept the new version of all configuration files and then hand-merge any customizations from saved original versions into the new configuration files, or go the other direction of merging changes in new files into the existing in-place original configuration files.

Upgrade (part 2): Upgrade the OpenNMS database and modify requisition files

Before starting OpenNMS again, perform an upgrade to the OpenNMS PostgreSQL database.

/usr/share/opennms/bin/install --do-database --insert-data --stored-procedure

or the equivalent

/usr/share/opennms/bin/install -dis

The installer will also upgrade any requisition files it finds to remove old XML attributes -- see Upgrade_Tools_for_1.12.

Upgrade (part 3): Merge old and new configuration files

Before starting OpenNMS again, merge old and new versions of configuration files together.

A side-by-side diff tool is very helpful for this process.

  • For Redhat-style systems, see http://wiki.freepbx.org/display/FD/Cleaning+up+files+from+a+RPM+update
  • For Debian/Ubuntu systems, the imediff2 tool can be installed with "sudo apt-get install imediff2", then see the above link for a helper script
    • This command can be used to locate old or new versions of configuration files on Debian/Ubuntu systems that need to be addressed:
 find /etc/opennms -name "*.dpkg-*"

After this, while OpenNMS is still running, run the upgrade command above again. This will merge old RRD database files with new ones.

/usr/share/opennms/bin/install --do-database --insert-data --stored-procedure

or the equivalent

/usr/share/opennms/bin/install -dis

Start OpenNMS

Start OpenNMS.


Java environment

It is recommended to install OpenJDK 7 or Oracle Java 7 JDK. If you have a white page after doing your upgrade. Please check if you have a JDK installed. The following error appears in your logs if you have just a JRE running:

 ErrorPageErrorHandler: EXCEPTION org.apache.jasper.JasperException: java.err.nojdk

Please make sure you have a JDK installed.

Configuration merge hints

This section shows configuration merge candidates from pristine 1.12.9 and 14.0.1 configuration directory.

Modified files

 modified:   chart-configuration.xml
 modified:   create.sql
 modified:   datacollection-config.xml
 modified:   datacollection/cisco.xml
 modified:   datacollection/ciscoNexus.xml
 modified:   datacollection/dell.xml
 modified:   datacollection/foundry.xml
 modified:   datacollection/mib2.xml
 modified:   datacollection/netsnmp.xml
 modified:   eventconf.xml
 modified:   events/BackupExec.events.xml
 modified:   events/DellArrayManager.events.xml
 modified:   events/DellOpenManage.events.xml
 modified:   events/DellRacHost.events.xml
 modified:   events/DellStorageManagement.events.xml
 modified:   examples/linkd-configuration.xml
 modified:   examples/monitoring-locations.xml
 modified:   examples/opennms.conf
 modified:   examples/threshd-configuration.xml
 modified:   jmx-datacollection-config.xml
 modified:   linkd-configuration.xml
 modified:   microblog-configuration.xml
 modified:   monitoring-locations.xml
 modified:   notificationCommands.xml
 modified:   opennms-datasources.xml
 modified:   opennms.properties
 modified:   opennms.service
 modified:   report-templates/AssetManagementMaintExpired.jrxml
 modified:   report-templates/AssetManagementMaintStrategy.jrxml
 modified:   report-templates/AvailabilitySummary.jrxml
 modified:   report-templates/AveragePeakTrafficRates.jrxml
 modified:   report-templates/DiskUsageForCTX.jrxml
 modified:   report-templates/Early-Morning-Report.jrxml
 modified:   report-templates/EventAnalysis.jrxml
 modified:   report-templates/InterfaceAvailabilityReport.jrxml
 modified:   report-templates/NodeAvailabilityReport.jrxml
 modified:   report-templates/ResponseTime.jrxml
 modified:   report-templates/ResponseTimeCharts.jrxml
 modified:   report-templates/ResponseTimeSummary.jrxml
 modified:   report-templates/SerialInterfaceUtilizationSummary.jrxml
 modified:   report-templates/SnmpInterfaceOperAvailabilityReport.jrxml
 modified:   report-templates/TotalBytesTransferredByInterface.jrxml
 modified:   report-templates/assets/styles/defaultStyles.jrtx
 modified:   report-templates/sample-report.jrxml
 modified:   report-templates/subreports/95thPercentileTrafficRate_subreport.jrxml
 modified:   report-templates/subreports/AvailabilitySummaryChart_subreport.jrxml
 modified:   report-templates/subreports/DiskUsageForCTXServers_subreport1.jrxml
 modified:   report-templates/subreports/InterfaceAvailabilityReport_subreport1.jrxml
 modified:   report-templates/subreports/PeakTraffic_subreport.jrxml
 modified:   report-templates/subreports/ResponseTimeAvg_subreport.jrxml
 modified:   report-templates/subreports/ResponseTimeSummary_Availability_Offenders_subreport.jrxml
 modified:   report-templates/subreports/ResponseTimeSummary_Availability_subreport.jrxml
 modified:   report-templates/subreports/ResponseTimeSummary_Response_Offenders_subreport.jrxml
 modified:   report-templates/subreports/ResponseTimeSummary_subreport.jrxml
 modified:   report-templates/subreports/ResponseTime_subreport1.jrxml
 modified:   report-templates/subreports/Top25PercentDown_subreport.jrxml
 modified:   report-templates/subreports/TotalBytesTransferredByInterface_subreport1.jrxml
 modified:   service-configuration.xml
 modified:   snmp-graph.properties
 modified:   snmp-graph.properties.d/hpux-graph.properties
 modified:   statsd-configuration.xml
 modified:   translator-configuration.xml
 modified:   vmware-datacollection-config.xml

Deleted files

 deleted:    access-point-monitor-configuration.xml
 deleted:    events-archiver-configuration.xml
 deleted:    events.archiver.properties
 deleted:    events/Dell.events.xml
 deleted:    events/Fortinet.events.xml
 deleted:    examples/jetty.xml
 deleted:    log4j-controller.properties
 deleted:    log4j.properties
 deleted:    report-templates/ResponseTime-sample.pdf
 deleted:    report-templates/leaf_banner_green.png
 deleted:    report-templates/opennms-logo.png
 deleted:    smsPhonebook.properties

Added new files


Upgrade hints

Warning.png Configuration merge

Use a virtual machine in a test environment to work on your configuration merges. So you can easily test with starting and stopping the system without stressing your people in production. You can use the backup from your production environment and turn off active parts from monitoring e.g. notifications and commenting in collectd and pollerd in service-configuration.xml.

Merging the configuration of OpenNMS is often a bigger issue. Helping to migrate your configuration it could be helpful to gitify your OpenNMS configuration directory. If you are not familiar with git you can find a good starting point Git to manage config files. One possible workflow can look like this:

  1. git init in /etc/opennms and make an initial commit with your current configuration
  2. git checkout -b production (Creates you a branch with your working configuration)
  3. git checkout -b upgrade-1.14 (Creates you a migration branch)
  4. Update opennms
  5. investigate changes and merge configs
  6. Commit the changes stepwise
  7. git checkout production
  8. git merge upgrade-1.14 and apply your merged configuration to "production" branch