Upgrade Guide: 1.8 to 1.10

From OpenNMS
Jump to: navigation, search

OpenNMS 1.10 is a major stable release, representing a year and a half of development, including complete support for IPv6, many performance improvements, massive updates to the provisioning subsystem, and much more. This guide will help you update from 1.8 to 1.10.

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

Upgrades from Older Releases

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


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

Backing Up the Database

It is always recommended that you use PostgreSQL's "custom" format when performing backups. PostgreSQL is much more flexible in how it deals with restores with the custom format.

To back up your OpenNMS database, run the following:

 pg_dump -U opennms -Fc -f /tmp/opennms.pgsql.gz opennms

This will create an "opennms.pgsql.gz" backup file in the /tmp directory.

Backing Up Configuration

All configuration is stored in the $OPENNMS_HOME/etc/ directory. It should be enough to back the entire directory up using tar or zip, like so:

 tar -cvzf /tmp/opennms-etc.tar.gz -C $OPENNMS_HOME etc

On Debian and Ubuntu, $OPENNMS_HOME/etc is a symlink, you should back up /etc/opennms instead:

 tar -cvzf /tmp/opennms-etc.tar.gz /etc/opennms

Backing Up RRDs

If you have the space, it's probably a good idea to back up your RRD data as well. Copy or tar up the contents of $OPENNMS_HOME/share/ if you wish to back them up as well. Note that your share directory can get VERY large, depending on the number of devices you're managing.

New Requirements

JDK 1.6

While we have been recommending JDK 1.6 for a while for performance reasons, OpenNMS 1.10 now requires JDK 1.6 or higher. We use some APIs that are only available in the 1.6 JDK.


Binary packages will depend on JICMP6 for IPv6 support. Most systems should get this automatically as part of the upgrade process.

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

Separated Protocol Plugins

A few protocols and plugins got split out into separate packages so they are not included in the default configuration. If you were using the following plugins, you will need to install the new opennms-plugin-protocol-xyz package and change your configuration to point to their new locations:

  • DHCP - install the optional "opennms-plugin-protocol-dhcp" package
    • capsd-configuration.xml - change "org.opennms.netmgt.capsd.plugins.DhcpPlugin" to "org.opennms.protocols.dhcp.capsd.DhcpPlugin"
    • poller-configuration.xml - change "org.opennms.netmgt.poller.monitors.DhcpMonitor" to "org.opennms.protocols.dhcp.monitor.DhcpMonitor"
    • service-configuration.xml - Dhcpd is commented out in the default 1.10 service configuration, make sure it is uncommented if you plan on using it
    • default-foreign-source.xml and foreign-sources/*.xml - change "org.opennms.netmgt.dhcp.detector.DhcpDetector" to "org.opennms.protocols.dhcp.detector.DhcpDetector"
  • NSClient/NSClientpp - install the optional "opennms-plugin-protocol-nsclient" package
    • capsd-configuration.xml - change "org.opennms.netmgt.capsd.plugins.NsclientPlugin" to "org.opennms.protocols.nsclient.capsd.NsclientPlugin"
    • poller-configuration.xml - change "org.opennms.netmgt.poller.monitors.NsclientMonitor" to "org.opennms.protocols.nsclient.monitor.NsclientMonitor"
    • collectd-configuration.xml - add the service as well as "<collector service="NSClientpp" class-name="org.opennms.protocols.nsclient.collector.NSClientCollector"/>" to the end
    • default-foreign-source.xml and foreign-sources/*.xml - change "org.opennms.netmgt.provision.detector.nsclient.NsclientDetector" to "org.opennms.protocols.nsclient.detector.NsclientDetector"
  • RADIUS - install the optional "opennms-plugin-protocol-radius" package
    • capsd-configuration.xml - change "org.opennms.netmgt.capsd.plugins.RadiusAuthPlugin" to "org.opennms.protocols.radius.capsd.RadiusAuthPlugin"
    • poller-configuration.xml - change "org.opennms.netmgt.poller.monitors.RadiusAuthMonitor" to "org.opennms.protocols.radius.monitor.RadiusAuthMonitor"
    • default-foreign-source.xml and foreign-sources/*.xml - change "org.opennms.netmgt.provision.detector.radius.RadiusAuthDetector" to "org.opennms.protocols.radius.detector.RadiusAuthDetector"
  • XMP - install the optional "opennms-plugin-protocol-xmp" package
    • collectd-configuration.xml - change "org.opennms.netmgt.collectd.XmpCollector" to "org.opennms.netmgt.protocols.xmp.collector.XmpCollector"
    • poller-configuration.xml - change "org.opennms.netmgt.poller.monitors.XmpMonitor" to "org.opennms.protocols.xmp.monitor.XmpMonitor"

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.10, and a number of the ThisMonth/LastMonth/ThisYear reports got merged such that a single report can take date ranges as argument. Keep that in mind while merging configuration conflicts.

Note that *.jrxml files in $OPENNMS_HOME/etc/report-templates/subreports will not be automatically recompiled, so be sure to copy over the new versions of the *.jasper intermediate-format files in this directory also. If you customized any of the subreport definitions that came with OpenNMS 1.8, you may need to update and recompile these.

Datacollection Configuration

Since 1.8, the SNMP data collection configuration has been modularized. If you made any changes to the datacollection-config.xml file, you will want to make a note of them, and apply them to the relevant individual file(s) in $OPENNMS_HOME/etc/datacollection/ or create a new file for your datacollection entries. If you create new datacollection files, note that you'll need to add an <include-collection /> reference in datacollection-config.xml.

Note that it is still possible to use the old 1.8 monolithic configuration style in 1.10, so you may copy your 1.8 datacollection-config.xml file over the 1.10 one, but you will lose any improvements made since 1.8, as well as make upgrades more difficult.

Note also that only the SNMP data collection configuration has been modularized so far. Other collectable protocols such as HTTP, NSClient, WMI, and XMP are unaffected by this change.

Warning.png IMPORTANT

When using the old datacollection-config.xml from 1.8 into 1.10, certain changes must be applied to that file as explained in NMS-4494, because of the new implementation of the SiblingColumnStorageStrategy. Otherwise, all data collection associated with any resource type which use that particular strategy won't be performed and some warning messages will appear in collectd.log as explained in NMS-4913, to let the user know about the problem.

Currently in 1.8, here is how a resource type based on SiblingColumnStorageStrategy looks:

<resourceType name="diskIOIndex" label="Disk IO (UCD-SNMP MIB)"
                  resourceLabel="${diskIODevice} (index ${index})">
  <persistenceSelectorStrategy class="org.opennms.netmgt.collectd.PersistAllSelectorStrategy"/>
  <storageStrategy class="org.opennms.netmgt.dao.support.SiblingColumnStorageStrategy">
    <parameter key="sibling-column-oid" value="." />
    <parameter key="replace-all" value="s/^-//" />
    <parameter key="replace-all" value="s/\\s//" />
    <parameter key="replace-all" value="s/:\\\\.*//" />

It should be changed to:

<resourceType name="diskIOIndex" label="Disk IO (UCD-SNMP MIB)"
                  resourceLabel="${diskIODevice} (index ${index})">
  <persistenceSelectorStrategy class="org.opennms.netmgt.collectd.PersistAllSelectorStrategy"/>
  <storageStrategy class="org.opennms.netmgt.dao.support.SiblingColumnStorageStrategy">
    <parameter key="sibling-column-name" value="diskIODevice" />
    <parameter key="replace-all" value="s/^-//" />
    <parameter key="replace-all" value="s/\s//" />
    <parameter key="replace-all" value="s/:\\.*//" />

The parameter sibling-column-oid has been replaced by sibling-column-name. This parameter uses any MibObj defined as string. All groups which use a resource type with SiblingColumnStorageStrategy, already contain a String MibObj that replaces the OID in the strategy. Also note the changes for the replace-all parameters (see NMS-5078 for more details).

SNMP Graph Configuration

While the snmp-graph.properties file has not been split up yet, it does support reading individual graph configuration from the $OPENNMS_HOME/etc/snmp-graph.properties.d directory:

 # include.directory is a directory which will be checked for files with 
 # names matching *.properties.  If it is a relative path (e.g. contains no path
 # delimiters), it is relative to the directory this file is in.
 # Each of those properties files will then be read and the graphs defined in
 # them added to the list of prefabricated graphs that are available.
 # Each of these included files can contain either a single graph, or multiple graphs.
 # If it includes multiple graphs, use the same format as this file, e.g.
 # a "reports" property listing the graph ids, and each graph is defined with 
 # a set of 'report.<graphname>.<key>' properties
 # If it includes just a single graph, you may use a short format.  In this format,
 # an additional property "report.id" defines the internal "name" of the graph, and 
 # all the other properties no longer require the graph name in the key. 
 # For example, such a single-graph file would look like this:
 #report.name=Bits In/Out
 #report.command=--title="Bits In/Out" \
 # --vertical-label="Bits per second" \
 # <rest of graph definition>
 # Graphs in the include directory that have the same id as one in this root file
 # will replace/override the one in this file.  

If you have previously modified the snmp-graph.properties file to add your own graph definitions, it is recommended that you instead put your changes into config files in the snmp-graph.properties.d directory, and revert to the original graph properties file to ease future upgrades.

IPv6 Support

By default, OpenNMS 1.10 will attempt to detect IPv4 and IPv6 support on the server, and if at least one is detected, start up. If you wish to be more deterministic in what is supported, please take note of the "ICMP" section of $OPENNMS_HOME/etc/opennms.properties upon upgrade:

 # ###### ICMP ######
 # OpenNMS provides three ICMP implementations. JICMP (legacy, IPv4-only),
 # JNA (supports both IPv4 and IPv6), and JICMP6.
 # The JICMP implementation is what has traditionally been used in OpenNMS
 # since 1.0, uses JNI.  It requires you to install a separate package
 # (JICMP) which contains a shared library for interfacing with your system's
 # The JICMP6 core library is a version of the JICMP codebase which can speak
 # ICMPv6, instead of ICMPv4. The OpeNMS JICMP6 pinger supports both ICMPv4
 # and ICMPv6.  It delegates all ICMPv4 ping requests to the original JICMP
 # JniPinger above and uses the JICMP6 library for ICMPv6 packets.  This is
 # the default for OpenNMS 1.9.90 and up.
 # Finally, the JNA implementation is written from the ground up to support
 # IPv4 and IPv6, and takes advantage of the JNA project's ability to access
 # native APIs without needing to distribute separate shared libraries.  It
 # is, however, not as performant as the JICMP6 pinger, so it is not
 # recommended unless you are in an environment which requires it.  This is
 # the default ICMP implementation used in the remote poller, since it does
 # not rely on any external native code to be installed outside of the JVM.
 # To use the JNI ICMPv4 interface only, use the following property setting:
 # To use the JNA ICMPv4/ICMPv6 implementation, use the following property:
 # The default is set to use the JNI ICMPv4/ICMPv6 interface like so:
 # By default, OpenNMS will start up if either ICMPv4 *or* ICMPv6 are
 # available and initialize properly.  If you wish to force IPv4 or IPv6
 # explicitly, set one or both of these properties to true or false.


The syslog daemon went under a significant rewrite to improve performance. By default, you can drop in a 1.8 syslogd-configuration.xml and it should continue to function, but you are strongly encouraged to look at the options for parsers documented at the top of 1.10's syslogd-configuration.xml file.

Additionally, the syslogd-configuration.xml file was modularized, to include individual configurations in the $OPENNMS_HOME/etc/syslog/ directory.

Web Application Changes

Tomcat Webapp Gone

While it was deprecated in 1.8, we have finally done away with the separate "tomcat" webapp. If you wish to run the web UI on a separate machine for scalability purposes, you can do so by creating a separate opennms instance with service-configuration.xml pared down to just jetty. Instructions on how to accomplish this are on the Jetty wiki page.

Spring Security Changes

If you have made any modifications to the jetty-webapps/opennms/WEB-INF/applicationContext-spring-security.xml file, you will want to be sure to merge the changes to a few paths:

userDao bean 
instead of "org.opennms.web.springframework.security.UserDaoImpl", the userDao class should now be "org.opennms.web.springframework.security.SpringSecurityUserDaoImpl", and includes 2 additional properties:
<beans:property name="userManager" ref="userManager" />
<beans:property name="groupManager" ref="groupManager" />
radiusAuthenticationProvider bean 
If you were using the RADIUS provider, you will need to install the opennms-plugin-protocol-radius package, and change the class from "org.opennms.web.springframework.security.RadiusAuthenticationProvider" to "org.opennms.protocols.radius.springsecurity.RadiusAuthenticationProvider"

Do It!

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 Tutorial page.

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