dstore-dist-eventforwarder

Configuring eventforwarder to Send Reports to Elasticsearch

The eventforwarder is used to process the messages related to DNS filtering events, and store them in Elasticsearch suitable for search/retrieval over a REST API provided by the report-api component. If DNS filtering is not in use in your environment, then eventforwarder and reporting-api are not required to be configured.

eventforwarder is configured using the configuration file eventforwarder.yml, which by default is located in /etc/pdns-dstore-dist/.

Events must be filtered in dstore-dist before sending to dstore-dist-top-reporter; this can be achieved in dstore-dist configuration using the filters configuration for a route. The filter should send only response messages and only messages with tags; this ensures that messages which are not associated with a DNS filtering event are not sent to eventforwarder. An example configuration for dstore-dist is shown below:

destinations:
  # Arbitrary names that can be referred to in routes
  mydestination:
    addresses:
      - "192.168.1.2:1234"
  routes:
    destinations:
      - mydestination
    filters:
      - has_tags: true
      - is_response: true

Configuring eventforwarder consists of specifying the Elasticsearch/Opensearch connection details, and specifying how eventforwarder will parse the tags present in the message to map to categories such as content filtering or malware.

An example eventforwarder configuration is shown below:

listen_addr: ":8332"

# Define filter types by tags.
filter_tags:
    contentfilter:
      - tagA
      - tagB
    malware: [tagC, tagD]
    blocklist:
      - tagE
    #phishing:
    #botnet:

elasticsearch:
    # Elasticsearch index where messages are sent.
    index: my-forwarder-index
    # Append the date to the index name to ensure a new index gets created each day
    add_date_to_index: true
    # The address of the elasticsearch server.
    addr: http://elasticsearch:9200
    # Auth username.
    user: elastic
    # Auth password.
    password: changeme

If a message is received which does not match any of the tags specified in filter_tags, then the report generated will not be useful, i.e. the report-api will ignore such reports.

For more information on the configuration of dstore-dist-eventforwarder, see dstore-dist-eventforwarder Configuration.