Upgrade Guide: 1.12 to 1.14
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.
- 1 Set OPENNMS_HOME
- 2 Upgrades from Older Releases
- 3 Backup OpenNMS 1.12.9
- 4 New Requirements
- 5 Preparing Your Configuration Files for Upgrade
- 6 Upgrade
- 7 Troubleshooting
- 8 Configuration merge hints
- 9 Upgrade hints
In this document,
$OPENNMS_HOME refers to the root of the OpenNMS installation. Usually, this is
/opt/opennms, or on Debian systems,
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 OPENNMS_HOME=/opt/opennms # Debian/Ubuntu systems OPENNMS_HOME=/usr/share/opennms # verify the path setting echo $OPENNMS_HOME
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.
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
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.
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.
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.
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.
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
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
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: 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: 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
datacollection/konica.xml enlinkd-configuration.xml events/Broadcom-BASPTrap.events.xml events/Dell-Asf.events.xml events/Dell-ITassist.events.xml events/Dlink.events.xml events/Fortinet-FortiCore-v4.events.xml events/Fortinet-FortiCore-v52.events.xml events/Fortinet-FortiGate-v4.events.xml events/Fortinet-FortiGate-v52.events.xml events/Fortinet-FortiMail.events.xml events/Fortinet-FortiManager-Analyzer.events.xml events/Fortinet-FortiRecorder.events.xml events/Fortinet-FortiVoice.events.xml events/FoundryNetworks2.events.xml events/INTEL-LAN-ADAPTERS-MIB.events.xml events/Konica.events.xml events/Trendmicro.events.xml events/topology-status.events.xml log4j2.xml snmp-hardware-inventory-adapter-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:
- git init in /etc/opennms and make an initial commit with your current configuration
- git checkout -b production (Creates you a branch with your working configuration)
- git checkout -b upgrade-1.14 (Creates you a migration branch)
- Update opennms
- investigate changes and merge configs
- Commit the changes stepwise
- git checkout production
- git merge upgrade-1.14 and apply your merged configuration to "production" branch