Setup

Here we assume that you already have:

Configure Elasticsearch persistence

From a Karaf shell on your Horizon instance, start by configuring the flow persistence to use your Elasticsearch cluster:

$ ssh -p 8101 admin@localhost
...
admin@opennms()> config:edit org.opennms.features.flows.persistence.elastic
admin@opennms()> config:property-set elasticUrl http://elastic:9200
admin@opennms()> config:update
This configuration is stored in $OPENNMS_HOME/etc/org.opennms.features.flows.persistence.elastic.cfg. See General Elasticsearch Configuration for a complete set of options.

Enabling a protocol

Next, enable one or more of the protocols you would like to handle in $OPENNMS_HOME/etc/telemetryd-configuration.xml.

In this example we enable the NetFlow v5 protocol, but you can repeat the same process for any of the other flow-related protocols.
Enable NetFlow v5 in telemetryd-configuration.xml
<listener name="Netflow-5-UDP-8877" class-name="org.opennms.netmgt.telemetry.listeners.UdpListener" enabled="true">
    <parameter key="port" value="8877"/>

    <parser name="Netflow-5-Parser" class-name="org.opennms.netmgt.telemetry.protocols.netflow.parser.Netflow5UdpParser" queue="Netflow-5" />
</listener>

<queue name="Netflow-5">
    <adapter name="Netflow-5-Adapter" class-name="org.opennms.netmgt.telemetry.protocols.netflow.adapter.netflow5.Netflow5Adapter" enabled="true">
    </adapter>
</queue>

Apply the changes without restarting by sending a reloadDaemonConfig event via the CLI:

Send a reloadDaemonConfig event through CLI
$OPENNMS_HOME/bin/send-event.pl -p 'daemonName Telemetryd' uei.opennms.org/internal/reloadDaemonConfig

This will open a UDP socket bound to 0.0.0.0:8877 to which NetFlow v5 messages can be forwarded.

To access flow-related graphs from the Horizon web interface, you must configure a link to your instance of OpenNMS Helm.

$ ssh -p 8101 admin@localhost
...
admin@opennms()> config:edit org.opennms.netmgt.flows.rest
admin@opennms()> config:property-set flowGraphUrl 'http://grafana:3000/dashboard/flows?node=$nodeId&interface=$ifIndex'
admin@opennms()> config:update
This URL can optionally point to other tools as well. It supports placeholders for $nodeId, $ifIndex, $start, and $end.

Once configured, an icon will appear on the top-right corner of a resource graph for an SNMP interface if there is flow data for that interface.

Configure a listener on a Minion

In this example, we enable a generic listener for the NetFlow v5 protocol on Minion.

NetFlow v5 uses the generic UDP listener, but other protocols require a specific listener. See the examples in $OPENNMS_HOME/etc/telemetryd-configuration.xml, or Telemetryd Listener Reference for details.

To enable and configure a listener for NetFlow v5 on Minion, connect to the Karaf Console and set the following properties:

$ ssh -p 8201 admin@localhost
...
admin@minion()> config:edit --alias udp-8877 --factory org.opennms.features.telemetry.listeners
admin@minion()> config:property-set name Netflow-5
admin@minion()> config:property-set class-name org.opennms.netmgt.telemetry.listeners.UdpListener
admin@minion()> config:property-set parameters.port 8877
admin@minion()> config:property-set parsers.0.name Netflow-5-Parser
admin@minion()> config:property-set parsers.0.class-name org.opennms.netmgt.telemetry.protocols.netflow.parser.Netflow5UdpParser
admin@minion()> config:update
If using a configuration management, you can create and use the properties file as startup configuration in $MINION_HOME/etc/org.opennms.features.telemetry.listeners-udp-8877.cfg. 
name = Netflow-5
class-name = org.opennms.netmgt.telemetry.listeners.UdpListener
parameters.port = 8877
parsers.0.name Netflow-5-Parser
parsers.0.class-name org.opennms.netmgt.telemetry.protocols.netflow.parser.Netflow5UdpParser
The associated protocol, in this case Netflow-5, must also be enabled on Horizon for the messages to be processed.

In some scenarios the exporter’s address is altered due to network address translation. In this case you can use node metadata to identify the exporter. Use the metaDataNodeLookup parameter to specify a context-key pair in the form of context:key for the lookup.

The value used for the lookup corresponds to the following fields from the various protocols:

Property Description

NetFlow v5

engineId

NetFlow v9

sourceId

IPFix

observationDomainId

SFlow

agent_address:sub_agent_id

BMP

bgpId

Node cache configuration

By default, each flow document, if Horizon can match the IP address to a node, is enriched with node information. To reduce the number of queries to the database, the data is cached.

The following cache properties are available to set in $OPENNMS_HOME/etc/org.opennms.features.flows.persistence.elastic.cfg:

Table 1. Optional parameters for the node cache
Property Description Default

nodeCache.maximumSize

The maximum size of the cache.

1000

nodeCache.expireAfterWrite

Number of seconds until an entry in the node cache is evicted. Set to 0 to disable eviction.

300

nodeCache.recordStats

Defines if cache statistics are exposed via JMX. Set to false to disable statistic recording.

true

Classification exporter filter cache configuration

A rule in the Classification Engine may define an exporterFilter. To resolve if the filter criteria match the address of an exporter, a database query is executed. A cache can be configured to cache the result to improve performance.

The following cache properties are available to set in $OPENNMS_HOME/etc/org.opennms.features.flows.classification.cfg:

Table 2. Optional parameters for the classification engine filters
Property Description Default

cache.classificationFilter.enabled

Enables or disables the cache.

false

cache.classificationFilter.maxSize

The maximum size of the cache.

5000

cache.classificationFilter.expireAfterRead

Number of seconds until an entry in the node cache is evicted. Set to 0 to disable eviction. The timer is reset every time an entry is read.

300

nodeCache.recordStats

Defines if cache statistics are exposed via JMX. Set to false to disable statistic recording.

true

Configure Kafka forwarder

Enriched flows (with OpenNMS node data) can also be forwarded to Kafka.

Enriched flows are stored in flowDocuments topic and the payloads are encoded using Google Protocol Buffers (GPB). See flowdocument.proto in the corresponding source distribution for the model definitions.

Enable Kafka forwarding:

$ ssh -p 8101 admin@localhost
...
admin@opennms()> config:edit org.opennms.features.flows.persistence.elastic
admin@opennms()> config:property-set enableForwarding true
admin@opennms()> config:update

Configure Kafka server for flows:

$ ssh -p 8101 admin@localhost
...
admin@opennms()> config:edit org.opennms.features.flows.persistence.kafka
admin@opennms()> config:property-set bootstrap.servers 127.0.0.1:9092
admin@opennms()> config:property-set topic opennms-flows
admin@opennms()> config:update

Correcting clock skew

Flow analyses use timestamps exposed by the underlying flow management protocol. These timestamps will be set depending on the clock of the exporting router. If the router’s clock differs from the actual time, this will be reflected in received flows and therefore skew up further analysis and aggregation.

Horizon Core can correct the timestamps of a received flow. To do so, it compares the current time of the exporting device with the actual time when the packet has been received. If these times differ by a certain amount, the receive time will be considered more correct and all timestamps of the flow will be adapted.

To enable clock correction, configure a threshold for the maximum allowed delta in milliseconds. Setting the threshold to 0 will disable the correction mechanism.

$ ssh -p 8101 admin@localhost
...
admin@opennms()> config:edit org.opennms.features.flows.persistence.elastic
admin@opennms()> config:property-set clockSkewCorrectionThreshold 5000
admin@opennms()> config:update