Managing Complex Configurations with XML ENTITY

UPDATE: Alejandro discovered that this method doesn’t work if you use Scheduled Outages as the webUI will write back the file as a single one and not preserve the ENTITY imports.

While we have made some serious strides toward making the OpenNMS configuration more modular, from my own humble contribution of include files in eventconf.xml, to breaking up datacollection-config.xml and, we still have some way to go to finish it for the rest of the application.

However, you can leverage a shortcut built into the XML standard to help manage files that can get complex. It allows you to import XML from one file to another.

It does have a limitation. Unlike the work we did with datacollection-config, etc., where we combined different parts of a configuration (generic resources, MIB object groups and system definitions) into separate files, this will only work if you can life whole sections out into other files.

One example would be the poller-configuration.xml file where you can remove entire sections. Here’s how you do it.

First, at the top of the file, you have to define the files you want to include:

<!DOCTYPE root [
  <!ENTITY pkg_Network-Connectivity SYSTEM "./etc/poller-configuration.d/pkg_Network-Connectivity.xml" >
  <!ENTITY pkg_StrafePing           SYSTEM "./etc/poller-configuration.d/pkg_strafePing.xml" >
  <!ENTITY pkg_Generic-Management   SYSTEM "./etc/poller-configuration.d/pkg_Generic-Management.xml" >

This will create a reference to the particular files you want to include. Then, to use them, you simply reference them at the proper place in the file:

<poller-configuration threads="900"
  <node-outage status="on" pollAllIfNoCriticalServiceDefined="true">
    <critical-service name="ICMP"/>

  <!-- Layer 3 network connectivity -->

   <!-- Layer 3 network diagnostics for jitter and latency -->

  <!-- Monitor for management agents and remote administration -->

Note that the ENTITY definitions come before the start of the “normal” XML for the file, i.e. in front of the initial <poller-configuration> tag.

This can make the management of unwieldy files a little easier.

Again, this only works for code that you can lift out in its entirety. In the case of poller-configuration.xml we still put the <monitor> tags down at the bottom of the main file.