Upgrade Horizon

This section outlines the basic steps that you should follow to upgrade to a newer version of Horizon. You may need to complete additional steps to upgrade in a more complex setup (for example, if you run more than one OpenNMS instance, have more complex database migration requirements, and/or depending on the age of current version).

A basic upgrade of one Horizon instance can take about an hour. This time varies, and will be longer depending on how customized and complex your setup is.

Before you begin

There are a number of tasks you should complete before starting an upgrade:

  • Check the Horizon release notes for breaking changes in each release between your current version and the version you want to upgrade to. Address any issues that might affect you.

    Currently, release notes for versions 28 and later are not available at the vault docs link (above). Please check the branches on GitHub for those release notes.
  • Stop the OpenNMS and PostgreSQL services.

  • Prune unneeded events.

  • Back up your database. (same day/state)

  • Back up RRD files. (same day/state)

  • Back up the ${OPENNMS_HOME}/etc directory. (same day/state)

  • Assess the events table size. This is especially important if you have a particularly large network with lots of events.

  • Identify any configuration files you have changed to determine what needs to be migrated as part of an upgrade.

Assess Events Table size

If, after pruning unneeded events, you still have a large number of events, you may need to increase the amount of memory passed to the OpenNMS install tool. For example, if you have 250,000 events, you will need almost 600MB of heap. When you upgrade and have the available memory, choose a large value to pass to the install:

${OPENNMS_HOME}/bin/install -Xms1024m -Xmx2048m -dis