Upgrading from 1.2.x to 1.6.x

From OpenNMS
Jump to navigation Jump to search

Note that these details apply to OpenNMS 1.3.2 and above

This wiki contains some notes that I made whilst upgrading from OpenNMS 1.2.x to 1.3.2_RELEASE. They may prove useful to others carrying out this process. Be aware that these notes were made a few weeks ago and therefore may not be current. They are also subject to transcription errors. If you find any mistakes, please correct them as necessary so that others may benefit.

Upgrading the Database

This was a fairly lengthy process, though the installer dealt with it manfully. Read The Installation Guide again.

prune any unwanted events

Should you not be doing this already, either using vacuumd or cron/sql, prune away any unneeded events. The events table will most probably be the largest, and there's no point backing up data that you don't need.

assess the size of the events table and adjust the installer heap

The installer tries for a maximum heap size of 256M. When I ran the installer for the first time, it fell over when it ran out of heap space. After a bit of experimentation with 260K events in the database (yes, I said 260K events) I found that the heap needed was around 580M. As I had RAM to spare on the database machine I went with:

-Xms1024m -Xmx2048m 

instead of the default

-Xmx256m 

in $OPENNMS_HOME/bin/install

which was probably wildy over the top. I reckon that -Xmx640m would have been adequate.

back up the database

Lastly, before you run the installer, and I cannot stress this enough, _back up the database_. Doing this saved my life when the installer ran out of heap.

/usr/local/pgsql/bin/pg_dump -C -f opennms_dump.sql opennms

Run the installer

When this is done, have a first go at running the installer:

$OPENNMS_HOME/bin/install -dis

If you're lucky this will work first time, however there are a lot more constraints on the database than there used to be, particularly requiring fields not to be null. Pay attention to the installer's output and refer back to the Common Installation Issues

Tomcat

OpenNMS 1.3.2 was developed using tomcat 5.5. Not 4.1, or 5.0, but 5.5, so for goodness sake, get that one.

The installer also takes modified options.

  1. There are no class libraries to be installed in $TOMCAT_HOME/server/lib, so there's no option to do that,
  2. The opennms webapp is not symlinked into $TOMCAT_HOME/webapps.
  3. Context configuration is stored in $TOMCAT_HOME/conf/<host name>/<engine name>/opennms.xml (by default $TOMCAT_HOME/conf/Catalina/localhost/opennms.xml), so there's an installer option to create this file.

Run the installer:

$OPENNMS_HOME/bin/install -y -w $TOMCAT_HOME/conf/Catalina/localhost/opennms.xml

Configuration Files

Now it's time to go through your config files with a fine-tooth comb.

  • categories.xml

no change in format from 1.2.x. I imported my previous configuration from 1.2.

  • viewsdisplay.xml

no change in format from 1.2.x. I imported my previous configuration from 1.2.

  • threshd-configuration.xml

This file now contains the castor class name (take care with this). Merge your previous configuration from 1.2. It also supports the "range" parameter in "service" entities to provide a "fudge factor" when comparing thresholds.

  • thresholds.xml

no change in format from 1.2.x. I imported my previous configuration from 1.2.

  • capsd-configuration.xml

Capsd plugins have moved. Instead of org.opennms.netmgt.capsd.<pluginname>, they are now at org.opennms.netmgt.capsd.plugins.<pluginname>. If you get this wrong, you will see log messages about failed plugin loading in capsd.log. There are some new plugins you might want to try, look in the examples directory in $OPENNMS_HOME/etc/.

  • collectd-configuration.xml

The file now contains the castor class name (take care with this). There are also some new services that you can collect from, written by Mike Jamison. If you dont want to use them immediately, you can turn them off.

  • magic-users.properties

no change in format from 1.2.x. I imported my previous configuration from 1.2.

  • service-configuration.xml

I took the defaults from 1.3. There are some new services, in particular linkd that are configured here. You will only change this file if you are enabling or disabling services.

  • jmx-datacollection-config.xml

This is all new stuff from Mike Jamison's JMX collector. You probably don't want to change anything in here.

  • http-datacollection-config.xml

This is all new stuff from the http collector. Unless you know what you want, leave this for now.

  • rrd-configuration.properties

This is changed from the 1.2 line. The default now to use the JrobinRrdStrategy, where is was previously to use the JniRrdStrategy. Whatever, you should not rely on the default to match your previous default settings.

  • events.archiver.properties

This file didn't exist in 1.2.x. There is nothing in here that you would want to change. I took the defaults from 1.3.

No change in format. I imported my previous configuration from 1.2.

  • response-graph.properties

This now has reponse times for JBoss (again added by Mike Jamison). It also has a new type property for each report. You will need to carefully merge any changes that you have made to this file into the new one.

  • vacuumd-configuration.xml

My copy was pretty old so I chose to accept the new one without changes.

  • actiond-configuration.xml

The default file was unchanged from the 1.2 line. I took the defaults from 1.3.

  • opennms-server.xml

There is nothing here that you would want to change. Take the defaults from 1.3

  • AvailabilityReports.xsl

If you have made any changes, you will need to carefully merge them in. Take the defaults from 1.3 unless you know what you're doing with this file.

  • PDFAvailReport.xsl

If you have made any changes, you will need to carefully merge them in. Take the defaults from 1.3 unless you know what you're doing with this file.

  • SVGAvailReport.xsl

If you have made any changes, you will need to carefully merge them in. Take the defaults from 1.3 unless you know what you're doing with this file.

  • poller-config.properties

This now has the JBOSS poller configuration. In the unlikely event that you have made any changes you will need to carefully merge them in. I took the defaults from 1.3.

  • groups.xml

My old groups.xml did not have an xmlns attribute. I had to add this, but the remainder of the format was unchanged.

  • map.disable

No we still dont much like maps ;-)

  • vulnscand-configuration.xml

There is nothing in here that you would want to change. I took the defaults from 1.3.

  • notifications.xml

This has gained an xmlns attribute since I last refreshed it, I needed to add this.

  • destinationPaths.xml

No changes in the format of this file since the 1.2 line.

  • exclude-ueis.properties

No changes. Its unlikely that you will have modified this file.

  • events-archiver-configuration.xml

No changes.

  • passive-status-configuration2.xml

This is a new file in 1.3. I obviously took the defaults from 1.3.

  • database-schema.xml

You don't want to change any of this. Take the defaults from 1.3.

  • webui-colors.xml

I don't really know what this file actually does. I took the defaults from 1.3.

  • log4j.properties

If you need any extended, logging, edit this accordingly. I took the default from 1.3.

  • notifd-configuration.xml

I took the default from 1.3, but checked to see that notifications were off before I started OpenNMS.

  • passive-status-configuration.xml

New file in 1.3 - don't mess with it (yet).

  • passive-status-configuration2.xml

New file in 1.3 - don't mess with it (yet)

  • notificationCommands.xml

This has recently gained a few new commands (including snmpTrap, http and XmppGroupMessage) you probably need to carefully merge any changes you have in. Basic format hasn't changed though.

  • xmlrpcd-configuration.xml

I don't use xmlrpcd. To be safe, I took the config from the 1.3 distribution.

  • poller-configuration.xml

This file had gained a castor class-name entity. I merged that in to my old file.

  • opennms-database.xml

Unless your database lives on a separate node, there's no need to change this. I took the defaults from 1.3.

  • datacollection-config.xml

This has gained some minor tweaks, at least since my version. I carefully merged my 1.2 version and the 1.3 default.

  • rtc-configuration.xml

There is nothing in here that you would wish to change.

  • discovery-configuration.xml

The format of this file is unchanged, I imported my previous configuration from 1.2.

  • ksc-performance-reports.xml

The format of this file is unchanged, I imported my previous configuration from 1.2.

  • castor.properties

There is nothing in here that you would wish to change. I took the default from the 1.3 dist.

  • jcifs.properties

There is nothing in here that you would wish to change. I took the default from the 1.3 dist.

  • notifications.dtd

There is nothing in here that you would wish to change. I took the default from the 1.3 dist.

  • snmp-adhoc-graph.properties

There is nothing in here that you would wish to change. I took the default from the 1.3 dist.

  • snmp-graph.properties

Carefully does it. The report type property values have changed. Reports generated at a node level use type nodeSnmp, reports generated using arbirary indexes at node level use a name that matches the resourceType definition in datacollection-configuration.xml. See the page on collecting from tables with arbitrary indexes for details.

  • dhcpd-configuration.xml

The format of this file has not changed, I imported my previous configuration from 1.2.

  • poll-outages.xml

The format of this file has not changed, I imported my previous configuration from 1.2.

  • trapd-configuration.xml

The content of this file has not changed. I took the defaults from 1.3.

  • chart-configuration.xml

This is a new file in 1.3. Obviously I took the defaults from 1.3.

  • response-adhoc-graph.properties

The content of this file has not changed. I took the defaults from1.3.

  • eventd-configuration.xml

There is nothing in this file that you would want to change. I took the defaults from 1.3.

  • eventconf.xml

There's a whole load of new events here. If you've added any, you've probably been clever and created new event configuration files in $OPENNMS_HOME/etc/events and imported them with event-file entities. If so, you can just go ahead and add them into the new file.

  • scriptd-configuration.xml

The content of this file has not changed. I took the defaults from 1.3.

  • snmp-config.xml

Mine did not have the port attribute set. Can also now use the ip-match attribute. You will need to merge your changes in by hand.

  • linkd-configuration.xml

New file in 1.3 - don't mess with it (yet) This service is commented out in the default services file

  • syslogd-configuration.xml

New file in 1.3 - don't mess with it (yet) This service is commented out in the default services file

Note: If you have any files that were "touched" by the webUI (i.e. castor) that are all one line, you will need to run, as root:

$OPENNMS_HOME/bin/xml.reader.pl -w [filename]

after the upgrade.