Verify configuration files

Changing configuration files is a key task operating an OpenNMS instance. OpenNMS comes with a configuration tester which helps you to identify configuration failures before they get loaded on a OpenNMS restart.

Test all configuration files

${OPENNMS_HOME}/bin/config-tester -a

Show a help output with all available options

${OPENNMS_HOME}/bin/config-tester -h

Debugging an unmarshalling failure

When a configuration file it uses the JAXB unmarshalling mechanisms as OpenNMS would use it during a restart. Beside detecting not well-formed XML errors you can also identify semantic errors in your configuration.

Here an example:

We have introduced an error in our poller-configuration.xml which says monitor services instead of monitor service. The XML is well-formed and will pass an xmllint run.

<monitor services="Web-Landing-Page-SSL" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>

Running the config-tester will tell you a different story. The attribute name “services” is not specified and you will get an error message like this:

[Exception [EclipseLink-25004] (Eclipse Persistence Services - 2.5.1.v20130918-f2b9fc5): org.eclipse.persistence.exceptions.XMLMarshalException
Exception Description: An error occurred unmarshalling the document
Internal Exception: org.xml.sax.SAXParseException; lineNumber: 181; columnNumber: 113; cvc-complex-type.3.2.2: Attribute 'services' is not allowed to appear in element 'monitor'.]
	at org.eclipse.persistence.jaxb.JAXBUnmarshaller.handleXMLMarshalException(JAXBUnmarshaller.java:980)
	at org.eclipse.persistence.jaxb.JAXBUnmarshaller.unmarshal(JAXBUnmarshaller.java:303)
	at org.opennms.core.xml.JaxbUtils.unmarshal(JaxbUtils.java:276)
	... 32 more
Caused by: Exception [EclipseLink-25004] (Eclipse Persistence Services - 2.5.1.v20130918-f2b9fc5): org.eclipse.persistence.exceptions.XMLMarshalException
Exception Description: An error occurred unmarshalling the document
Internal Exception: org.xml.sax.SAXParseException; lineNumber: 181; columnNumber: 113; cvc-complex-type.3.2.2: Attribute 'services' is not allowed to appear in element 'monitor'.
	at org.eclipse.persistence.exceptions.XMLMarshalException.unmarshalException(XMLMarshalException.java:114)
	at org.eclipse.persistence.internal.oxm.record.SAXUnmarshaller.convertSAXException(SAXUnmarshaller.java:999)
	at org.eclipse.persistence.internal.oxm.record.SAXUnmarshaller.unmarshal(SAXUnmarshaller.java:496)
	at org.eclipse.persistence.internal.oxm.record.SAXUnmarshaller.unmarshal(SAXUnmarshaller.java:695)
	at org.eclipse.persistence.oxm.XMLUnmarshaller.unmarshal(XMLUnmarshaller.java:655)
	at org.eclipse.persistence.jaxb.JAXBUnmarshaller.unmarshal(JAXBUnmarshaller.java:301)
	... 33 more
Caused by: org.xml.sax.SAXParseException; lineNumber: 181; columnNumber: 113; cvc-complex-type.3.2.2: Attribute 'services' is not allowed to appear in element 'monitor'.
	at org.apache.xerces.util.ErrorHandlerWrapper.createSAXParseException(Unknown Source)
	at org.apache.xerces.util.ErrorHandlerWrapper.error(Unknown Source)
	at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
	at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
	at org.apache.xerces.impl.XMLErrorReporter.reportError(Unknown Source)
	at org.apache.xerces.impl.xs.XMLSchemaValidator$XSIErrorReporter.reportError(Unknown Source)
	at org.apache.xerces.impl.xs.XMLSchemaValidator.reportSchemaError(Unknown Source)
	at org.apache.xerces.impl.xs.XMLSchemaValidator.processAttributes(Unknown Source)
	at org.apache.xerces.impl.xs.XMLSchemaValidator.handleStartElement(Unknown Source)
	at org.apache.xerces.impl.xs.XMLSchemaValidator.startElement(Unknown Source)
	at org.apache.xerces.jaxp.validation.ValidatorHandlerImpl.startElement(Unknown Source)
	at org.eclipse.persistence.internal.oxm.record.XMLReader$ValidatingContentHandler.startElement(XMLReader.java:431)
	at org.xml.sax.helpers.XMLFilterImpl.startElement(XMLFilterImpl.java:551)
	at org.opennms.core.xml.SimpleNamespaceFilter.startElement(SimpleNamespaceFilter.java:83)
	at org.apache.xerces.parsers.AbstractSAXParser.startElement(Unknown Source)
	at org.apache.xerces.parsers.AbstractXMLDocumentParser.emptyElement(Unknown Source)
	at org.apache.xerces.impl.XMLNSDocumentScannerImpl.scanStartElement(Unknown Source)
	at org.apache.xerces.impl.XMLDocumentFragmentScannerImpl$FragmentContentDispatcher.dispatch(Unknown Source)
	at org.apache.xerces.impl.XMLDocumentFragmentScannerImpl.scanDocument(Unknown Source)
	at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
	at org.apache.xerces.parsers.XML11Configuration.parse(Unknown Source)
	at org.apache.xerces.parsers.XMLParser.parse(Unknown Source)
	at org.apache.xerces.parsers.AbstractSAXParser.parse(Unknown Source)
	at org.xml.sax.helpers.XMLFilterImpl.parse(XMLFilterImpl.java:357)
	at org.eclipse.persistence.internal.oxm.record.XMLReader.parse(XMLReader.java:221)
	at org.eclipse.persistence.internal.oxm.record.SAXUnmarshaller.unmarshal(SAXUnmarshaller.java:492)
	... 36 more

The important part here is:

Internal Exception: org.xml.sax.SAXParseException; lineNumber: 181; columnNumber: 113; cvc-complex-type.3.2.2: Attribute 'services' is not allowed to appear in element 'monitor'.]

Which give you hints where you can find errors in your configuration file.

4 Likes

Thanks Ronny, this is a great tool. Will this also work for XML event files? I recently had an issue with an event file where I used an upper case letter where I should have used lower case. It took some time to comb through log files to find the issue. I just introduced the same error in the event file and ran this tool, but it did not indicate an issue.

We have on a few places extremely loose contracts between configurations, e.g. the service name in a poller configuration and the class which executes that configuration. Another one is the service name provisioned to an IP interface and service polling and data collection. I guess you ran into a similar case in events.

Can you provide an example what was not covered, maybe we can extend the configuration test tool to figure those things out.