Guidance to migrate configuration files on update

update
how-to

#1

Upgrade Guide

This guide is based on the information from How to figure out which configurations are changed from a pristine install, to show the workflow with an example.

General

The command colordiff, which is provided in Debian and Red Hat based distributions as well, is more handy since it colors the output.

So lets diff your configs with the pristine ones:

[11:17]root@opennms:/etc/opennms# colordiff -rq -EBbw /etc/opennms/ /usr/share/opennms/share/etc-pristine
Files /etc/opennms/config.properties and /usr/share/opennms/share/etc-pristine/config.properties differ
Only in /etc/opennms/: configured
Files /etc/opennms/discovery-configuration.xml and /usr/share/opennms/share/etc-pristine/discovery-configuration.xml differ
Only in /etc/opennms/: examples
Only in /etc/opennms/: foreign-sources
Only in /etc/opennms/: imports
Only in /etc/opennms/: java.conf
Only in /etc/opennms/: jmx.acl.org.apache.camel.cfg
Only in /etc/opennms/: libraries.properties
Files /etc/opennms/notifd-configuration.xml and /usr/share/opennms/share/etc-pristine/notifd-configuration.xml differ
Only in /etc/opennms/: opennms.conf
Files /etc/opennms/opennms-datasources.xml and /usr/share/opennms/share/etc-pristine/opennms-datasources.xml differ
Files /etc/opennms/opennms.properties and /usr/share/opennms/share/etc-pristine/opennms.properties differ
Only in /etc/opennms/: opennms-upgrade-status.properties
Only in /etc/opennms/: pluginManifestData.xml
Files /etc/opennms/poller-configuration.xml and /usr/share/opennms/share/etc-pristine/poller-configuration.xml differ
Files /etc/opennms/service-configuration.xml and /usr/share/opennms/share/etc-pristine/service-configuration.xml differ

The length and complexity of the output depends on the amount of customizations.
In the example above you can see three cases.

  1. File only exists in the pristine folder
    In this case we don’t have that case.
  2. File only exists in the running configuration
    Custom config was created, eg. Drools rules, data collection configs etc.
  3. File differs
    Changes in the original config was made which is usually the biggest part

Depending on the amount of changes it can be useful to separate the output using grep.

1. File only exists in Pristine folder

All configuration files which exists in pristine but not in your configuration folder can be ignore in the first place.

2. Custom config

All these files are created and do not exist in a pristine configuration.
You have to ensure to migrate these files into your new OpenNMS Horizon version.

Example:

[11:20]root@opennms:/etc/opennms# diff -rq -EBbw /etc/opennms/ /usr/share/opennms/share/etc-pristine | grep "Only in /etc/opennms"
Only in /etc/opennms/: configured
Only in /etc/opennms/: examples
Only in /etc/opennms/: foreign-sources
Only in /etc/opennms/: imports
Only in /etc/opennms/: java.conf
Only in /etc/opennms/: jmx.acl.org.apache.camel.cfg
Only in /etc/opennms/: libraries.properties
Only in /etc/opennms/: opennms.conf
Only in /etc/opennms/: opennms-upgrade-status.properties
Only in /etc/opennms/: pluginManifestData.xml

3. Differing files

These are the most difficult files because they need special attention while merging.

[11:18]root@opennms:/etc/opennms# diff -rq -EBbw /etc/opennms/ /usr/share/opennms/share/etc-pristine | grep "differ" 
Files /etc/opennms/config.properties and /usr/share/opennms/share/etc-pristine/config.properties differ
Files /etc/opennms/discovery-configuration.xml and /usr/share/opennms/share/etc-pristine/discovery-configuration.xml differ
Files /etc/opennms/notifd-configuration.xml and /usr/share/opennms/share/etc-pristine/notifd-configuration.xml differ
Files /etc/opennms/opennms-datasources.xml and /usr/share/opennms/share/etc-pristine/opennms-datasources.xml differ
Files /etc/opennms/opennms.properties and /usr/share/opennms/share/etc-pristine/opennms.properties differ
Files /etc/opennms/poller-configuration.xml and /usr/share/opennms/share/etc-pristine/poller-configuration.xml differ
Files /etc/opennms/service-configuration.xml and /usr/share/opennms/share/etc-pristine/service-configuration.xml differ

To see the differences in detail use the command below.

Example:

[11:18]root@opennms:/etc/opennms# colordiff -r -EBbw /etc/opennms/ /usr/share/opennms/share/etc-pristine
diff -r -EBbw /etc/opennms/config.properties /usr/share/opennms/share/etc-pristine/config.properties
408,412d407
< # Generated command shutdown
< #
< karaf.shutdown.command = 0e02576b-1018-48f8-acbc-3f4cb69ecc48
< 
< #
Only in /etc/opennms/: configured
diff -r -EBbw /etc/opennms/discovery-configuration.xml /usr/share/opennms/share/etc-pristine/discovery-configuration.xml
1c1
< <?xml version="1.0" encoding="UTF-8"?><discovery-configuration xmlns="http://xmlns.opennms.org/xsd/config/discovery" initial-sleep-time="30000" packets-per-second="1" restart-sleep-time="86400000" retries="1" timeout="2000">
---
> <discovery-configuration xmlns="http://xmlns.opennms.org/xsd/config/discovery" packets-per-second="1" initial-sleep-time="30000" restart-sleep-time="86400000" retries="1" timeout="2000">
Only in /etc/opennms/: examples
Only in /etc/opennms/: foreign-sources
Only in /etc/opennms/: imports
Only in /etc/opennms/: java.conf
Only in /etc/opennms/: jmx.acl.org.apache.camel.cfg
Only in /etc/opennms/: libraries.properties
diff -r -EBbw /etc/opennms/notifd-configuration.xml /usr/share/opennms/share/etc-pristine/notifd-configuration.xml
1c1
< <notifd-configuration xmlns="http://xmlns.opennms.org/xsd/config/notifd" status="on" match-all="true">
---
> <notifd-configuration xmlns="http://xmlns.opennms.org/xsd/config/notifd" status="off" match-all="true">
Only in /etc/opennms/: opennms.conf
diff -r -EBbw /etc/opennms/opennms-datasources.xml /usr/share/opennms/share/etc-pristine/opennms-datasources.xml
2,3c2,18
< <datasource-configuration>
<   <connection-pool factory="org.opennms.core.db.C3P0ConnectionFactory"
---
> <datasource-configuration xmlns:this="http://xmlns.opennms.org/xsd/config/opennms-datasources" 
>   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
>   xsi:schemaLocation="http://xmlns.opennms.org/xsd/config/opennms-datasources 
>   http://www.opennms.org/xsd/config/opennms-datasources.xsd ">
> 
>   <!-- 
>     Available implementations:
> 
>       org.opennms.core.db.C3P0ConnectionFactory
>         - Uses C3P0 (http://sourceforge.net/projects/c3p0/).
>           This data source is not XA-capable but is available because it was the default
>           datasource on OpenNMS 1.12. It is well tested as a reliable database pool.
> 
>       org.opennms.core.db.HikariCPConnectionFactory
>         - Uses HikariCP (http://brettwooldridge.github.io/HikariCP/), a lightweight and extremely fast connection pool
>    -->
>   <connection-pool factory="org.opennms.core.db.HikariCPConnectionFactory"
21,22c36,37
<                     user-name="opennms"
<                     password="opennms" />
---
>                     user-name="postgres"
>                     password="" />
diff -r -EBbw /etc/opennms/opennms.properties /usr/share/opennms/share/etc-pristine/opennms.properties
140c140
< org.opennms.rrd.storeByForeignSource=true
---
> org.opennms.rrd.storeByForeignSource=false
608c608
< opennms.nodeStatusBar.show=true
---
> #opennms.nodeStatusBar.show=false
Only in /etc/opennms/: opennms-upgrade-status.properties
Only in /etc/opennms/: pluginManifestData.xml
diff -r -EBbw /etc/opennms/poller-configuration.xml /usr/share/opennms/share/etc-pristine/poller-configuration.xml
287,293d286
<       <service name="NTP" interval="60000" user-defined="true" status="on">
<          <parameter key="retry" value="2"/>
<          <parameter key="timeout" value="1000"/>
<          <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
<          <parameter key="rrd-base-name" value="ntp"/>
<          <parameter key="ds-name" value="ntp"/>
<       </service>
361d353
<    <monitor service="NTP" class-name="org.opennms.netmgt.poller.monitors.NtpMonitor"/>

A small explanation using the file opennms.properties as an example.
There are two rows differing.
Option org.opennms.rrd.storeByForeignSource was originally false but is in the current config true.
Option opennms.nodeStatusBar was commented with # and was set to false and is not commented out and set to true.

diff -r -EBbw /etc/opennms/opennms.properties /usr/share/opennms/share/etc-pristine/opennms.properties
140c140
< org.opennms.rrd.storeByForeignSource=true
---
> org.opennms.rrd.storeByForeignSource=false
608c608
< opennms.nodeStatusBar.show=true
---
> #opennms.nodeStatusBar.show=false