Upgrading from 1.2.x to 1.6.x
Contents
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.
- There are no class libraries to be installed in $TOMCAT_HOME/server/lib, so there's no option to do that,
- The opennms webapp is not symlinked into $TOMCAT_HOME/webapps.
- 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.
