Event Daemon Configuration

The back-end configuration surrounding events is split into two areas: the configuration of eventd itself, and the configuration of events definitions known to Horizon.

The eventd-configuration.xml file

The overall behavior of eventd is configured in the ${OPENNMS_HOME}/etc/eventd-configuration.xml file. This file does not need to be changed in most installations. The configurable items include the following:

TCPAddress

The IP address to which the eventd XML/TCP listener will bind. Defaults to 127.0.0.1.

TCPPort

The TCP port number on TCPAddress to which the eventd XML/TCP listener will bind. Defaults to 5817.

UDPAddress

The IP address to which the eventd XML/UDP listener will bind. Defaults to 127.0.0.1.

UDPPort

The UDP port number on TCPAddress to which the eventd XML/UDP listener will bind. Defaults to 5817.

receivers

The number of threads allocated to service the event intake work done by eventd.

queueLength

The maximum number of events that may be queued for processing. Additional events will be dropped. Defaults to unlimited.

getNextEventID

An SQL query statement used to retrieve the ID of the next new event. Changing this setting is not recommended.

socketSoTimeoutRequired

Whether to set a timeout value on the eventd receiver socket.

socketSoTimeoutPeriod

The socket timeout, in milliseconds, to set if socketSoTimeoutRequired is set to yes.

logEventSummaries

Whether to log a simple (terse) summary of every event at level INFO. Useful when troubleshooting event processing on busy systems where DEBUG logging is not practical.

The set of known events is configured in ${OPENNMS_HOME}/etc/eventconf.xml. This file opens with a <global> element, whose <security> child element defines which event fields may not be overridden in the body of an event submitted via any eventd listener. This mechanism stops a malicious actor from, for instance, sending an event whose operator-action field amounts to a phishing attack.

After the <global> element, this file consists of a series of <event-file> elements. The content of each <event-file> element specifies the path of a tributary file whose contents will be read and incorporated into the event configuration. These paths are resolved relative to the ${OPENNMS_HOME}/etc directory; absolute paths are not allowed.

Each tributary file contains a top-level <events> element with one or more <event> child elements. Consider the following event definition:

<event>
    <uei>uei.opennms.org/nodes/nodeLostService</uei>
    <event-label>OpenNMS-defined node event: nodeLostService</event-label>
    <descr>&lt;p>A %service% outage was identified on interface
        %interface% because of the following condition: %parm[eventReason]%.&lt;/p> &lt;p>
        A new outage record has been created and service-level
        availability calculations will be impacted until this outage is
        resolved.&lt;/p></descr>
    <logmsg dest="logndisplay">
        %service% outage identified on interface %interface%.
    </logmsg>
    <severity>Minor</severity>
    <alarm-data reduction-key="%uei%:%dpname%:%nodeid%:%interface%:%service%" alarm-type="1" auto-clean="false"/>
</event>

Every event definition has this same basic structure. See Anatomy of an event for a discussion of the structural elements.

A word about severities

When setting event severities, it’s important to consider each event in the context of your infrastructure as a whole. Events whose severity is critical at the zoomed-in level of a single device may not merit a Critical severity in the zoomed-out view of your entire enterprise. Since an event with Critical severity can never have its alarms escalated, you should usually reserve this highest severity level for events that unequivocally indicate a truly critical impact to the business. Rock legend Nigel Tufnel offered some wisdom on the subject.

Structure of the eventconf.xml tributary files

The order of event definitions is very important, as an incoming event is matched against them in order. It is possible, and often useful, to have several event definitions that could match variant forms of a given event; for example, based on the values of SNMP trap variable bindings.

The tributary files included via the <event-file> tag have been broken up by vendor. When Horizon starts, each tributary file is loaded in order. The ordering of events inside each tributary file is also preserved.

The tributary files listed at the end of eventconf.xml contain catch-all event definitions. When slotting your own event definitions, take care not to place them below these catch-all files; otherwise your definitions will be effectively unreachable.

A Few Tips

  • To save memory and shorten startup times, you may want to remove event definition files that you know you do not need.

  • If you need to customize some events in one of the default tributary files, you may want to make a copy of the file containing only the customized events and load the copy above the original in eventconf.xml. This practice will make it easier to maintain your customizations in case the default file changes in a future release of Horizon.

Reloading the event configuration

After making manual changes to ${OPENNMS_HOME}/etc/eventconf.xml or any of its tributary files, you must restart the eventd daemon. You can trigger a reload of the daemon in the Karaf shell or by issuing the following command on the Horizon server:

$\{OPENNMS_HOME}/bin/send-event.pl uei.opennms.org/internal/reloadDaemonConfig -p 'daemonName Eventd'