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.

Eventd configuration

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

Eventd configuration parameters
Parameter	Description	Default Value
TCPAddress	The IP address to which the eventd XML/TCP listener binds.	127.0.0.1
TCPPort	The TCP port number on the IP address defined by `TCPAddress` to which the eventd XML/TCP listener binds.	5817
UDPAddress	The IP address to which the eventd XML/UDP listener binds.	127.0.0.1
UDPPort	The UDP port number on the IP address defined by `UDPAddress` to which the eventd XML/UDP listener binds.	5817
receivers	The number of hreads allocated to service the event intake work done by eventd.	Blank
queueLength	The maximum number of events that may be queued for processing. Additional events are dropped.	Unlimited
getNextEventID	A SQL query statement that is 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 socket.	no
socketSoTimeoutPeriod	The socket timeout, in milliseconds, to set if `socketSoTimeoutRequired` is enabled.	Blank
logEventSummaries	Whether to log a simple (terse) summary of every event at the `INFO` level. This is 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 accepted.

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 is 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.

Operational status representations
Name	Description	Numerical Code
Critical	Indicates a severe service-affecting event has occurred.	7
Major	Indicates serious disruption or malfunction of a service or system.	6
Minor	Used for troubles that have no immediate effect on service or system performance.	5
Warning	An event has occurred that may require action. This severity indicates a condition that should be logged, but does not require immediate action.	4
Normal	Informational message. No action required.	3
Cleared	Reserved for use in alarms to indicate that they describe self-clearing error conditions that have been corrected, and service is restored. Never use this severity in event definitions. Use "Normal" severity for events that clear an alarm.	2
Indeterminate	No severity could be associated with this event.	1

Structure of 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.

At level DEBUG, eventd will log a verbose description of every event it handles to ${OPENNMS_HOME}/logs/eventd.log. On busy systems, this setting may create so much noise as to be impractical. In these cases, you can get terse event summaries by setting eventd to log at level INFO and setting logEventSummaries="yes" in ${OPENNMS_HOME}/etc/eventd-configuration.xml. Note that changes to eventd-configuration.xml require a full restart of Horizon.

Karaf Shell

Use the opennms:show-event-config command to render the event definition for one or more event UEIs (matching a substring) to XML. This command is useful for displaying event definitions that may not be easily accessible on disk, or verifying that particular events were actually loaded.

$ ssh -p 8101 admin@localhost
...
admin@opennms()> opennms:show-event-config -u uei.opennms.org/alarms

Reload 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'