# 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

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 Default Description nodeCache.maximumSize 1000 The maximum size of the cache. nodeCache.expireAfterWrite 300 Number of seconds until an entry in the node cache is evicted. Set to 0 to disable eviction. nodeCache.recordStats true Defines if cache statistics are exposed via JMX. Set to `false` to disable statistic recording. ## 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 Default Description

cache.classificationFilter.enabled

false

Enables or disables the cache.

cache.classificationFilter.maxSize

5000

The maximum size of the cache.

300

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.

nodeCache.recordStats

true

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

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

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