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.
| 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 |
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 |
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 |
Blank |
logEventSummaries |
Whether to log a simple (terse) summary of every event at the |
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><p>A %service% outage was identified on interface
%interface% because of the following condition: %parm[eventReason]%.</p> <p>
A new outage record has been created and service-level
availability calculations will be impacted until this outage is
resolved.</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.
| 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.
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'