Event Configuration

The back-end configuration surrounding events is broken into two areas: the configuration of Eventd itself, and the configuration of all types of events known to Meridian.

The eventd-configuration.xml file

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

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, this severity level should usually be reserved for events that unequivocally indicate a truly critical impact to the business. Rock legend Nigel Tufnel offered some wisdom on the subject.

Replacement tokens

You can include various tokens in the description, log message, operator instruction, and automatic actions for each event. These tokens will be replaced by values from the current event when the text for the event is constructed. Not all events will have values for all tokens, and some refer specifically to information available only in events derived from SNMP traps.

Note that parameter descriptions use the percentage sign (%) as a delimiter to mark a replacement variable. If a literal % sign appears in your description, you must escape it with a %. For example:

'testUrl https://www.opennms.org/ReportSection?filter=FOO_BAR_BAZ%%20eq%%20%%27101%%27'

%eventid%

The event’s numeric database ID.

%uei%

The unique event identifier for the event.

%source%

The source of the event (which Meridian service daemon created it).

%descr%

The event description.

%logmsg%

The event logmsg.

%time%

The time of the event.

%shorttime%

The time of the event formatted using DateFormat.SHORT for a completely numeric date/time.

%dpname%

Formerly used for the ID of the Minion that the event was received on. This placeholder is deprecated and will be resolved to an empty string.

%nodeid%

The numeric node ID of the device that caused the event, if any.

%nodelabel%

The node label for the node given in %nodeid%, if available.

%nodelocation%

The node location for the node given in %nodeid%, if available.

%host%

The host at which the event was generated.

%interface%

The IP interface associated with the event, if any.

%foreignsource%

The requisition name for the node given in %nodeid if available.

%foreignid%

The requisition ID for the node given in %nodeid if available.

%ifindex%

The interface’s SNMP ifIndex.

%interfaceresolv%

Does a reverse lookup on the %interface% and returns its name, if available.

%service%

The service associated with the event, if any.

%severity%

The severity of the event.

%snmphost%

The host of the SNMP agent that generated the event.

%id%

The SNMP enterprise OID for the event.

%trapoid%

Full trap OID for the event.

%idtext%

The decoded (human-readable) SNMP Enterprise OID for the event.

%ifalias%

The interface’s SNMP ifAlias.

%generic%

The generic trap-type number for the event.

%specific%

The specific trap-type number for the event.

%community%

The community string for the trap.

%version%

The SNMP version of the trap.

%snmp%

The SNMP information associated with the event.

%operinstruct%

The operator instructions for the event.

%mouseovertext%

The mouse over text for the event.

%tticketid%

The trouble ticket ID associated with the event, if available.

%primaryinterface%

The primary interface IP address for the node given in %nodeid%, if available.

The use of multiple Minions in one location can break the alarm life-cycle for a some OpenNMS features. To avoid this problem, the %dpname% value can always be replaced by an empty string by setting org.opennms.netmgt.eventd.cleardpname to true in the file opennms.properties.

Asset tokens

A node may have additional asset records stored for it. You can access these records using the asset replacement token, which takes the form:

%asset[<token>]%

The asset field <token>'s value, or "Unknown" if it does not exist.

Hardware tokens

A node may have additional hardware details stored for it. You can access these details using the hardware replacement token, which takes the form:

%hardware[<token>]%

The hardware field <token>'s value.

Parameter tokens

Many events carry additional information in parameters (see Anatomy of an Event). These parameters may start life as SNMP trap variable bindings, or varbinds for short. You can access event parameters using the parm replacement token, which takes several forms:

%parm[all]%

Space-separated list of all parameter values in the form parmName1="parmValue1" parmName2="parmValue2" and so on.

%parm[values-all]%

Space-separated list of all parameter values (without their names) associated with the event.

%parm[names-all]%

Space-separated list of all parameter names (without their values) associated with the event.

%parm[<name>]%

Return the value of the parameter named <name> if it exists.

%parm[##]%

Will return the total number of parameters as an integer.

%parm[#<num>]%

Will return the value of parameter number <num> (one-indexed).

%parm[name-#<num>]%

Will return the name of parameter number <num> (one-indexed).

The structure of the eventconf.xml tributary files

The ordering 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 which 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 Meridian 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 wish 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 wish to make a copy of the file containing only the customized events, and slot the copy above the original; this practice will make it easier to maintain your customizations in case the default file changes in a future release of Meridian.

Reloading the Event configuration

After making manual changes to ${OPENNMS_HOME}/etc/eventconf.xml or any of its tributary files, you can trigger a reload of the event configuration by issuing the following command on the Meridian server:

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

Debugging

When debugging events, it may be helpful to lower the minimum severity at which Eventd will log from the default level of WARN. To change this setting, edit ${OPENNMS_HOME}/etc/log4j2.xml and locate the following line:

<KeyValuePair key="eventd"               value="WARN" />

Changes to log42.xml will take effect within 60 seconds with no extra action needed. 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 Meridian.

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