NAME

dstore-dist-eventforwarder - daemon to forward filtered events to external services for reporting purposes

SYNOPSIS

dstore-dist-eventforwarder [-addr ip:port] [-config file] [-debug] [-es-addr url] [-es-api-key key] [-es-cloud-id id] [-es-index index] [-es-pass password] [-es-user user] [-nconcur num]

DESCRIPTION

dstore-dist-eventforwarder receives events from dstore-dist, converts them to a JSON format that is suitable for ingestion by external services such as elasticsearch, and forwards the events on to those services. The initial version only supports forwarding the events to Elasticsearch, although future versions may support forwarding to other services, such as a generic HTTP Webhook endpoint. dstore-dist-eventforwarder differs from dstore-dist in that it both simplifies the event data (removing many of the low-level fields, and any response data), while simultaneously enriching it by attempting to categorize events based on the tags present in those events. The dstore-dist-eventforwarder is only suitable for forwarding events filtered by PowerDNS Platform Filter, which can be achieved by for example using the the has_tags filter in dstore-dist.

OPTIONS

-addr string: IP:port to listen (default “:8332”)

-config string: Path to config file

-debug: Enable debug log level

-es-addr string: Elasticsearch server address

-es-api-key string: Elasticsearch API key

-es-cloud-id string: Elasticsearch cloud id

-es-index string: Elasticsearch index name

-es-pass string: Elasticsearch password

-es-user string: Elasticsearch username

-nconcur int: Number of concurrent senders, a value <= 0 means default (default 16)

-help: Display a helpful message and exit.

CONFIGURATION FILE FORMAT

The following YAML fields are supported for configuration:

• listen_addr: The address to listen for new connections. Events should be in standard PowerDNS protobuf format, delimited with a 16-bit network byte order length field.

listen_addr: ":8332"

• tlsconfig: A map consisting of server tls configuration parameters. If not configured, the server will not use TLS to receive events.

  • require_client_cert: Controls whether the server verifies the client’s certificate. Defaults to false.
  • ca_file: Optional CA file to use (PEM).
  • ca: Optional CA to use specified as a string in PEM format.
  • add_system_ca_pool: Adds the system CA pool if private CAs are enabled, when set. Defaults to false.
  • cert_file: Optional certificate file to use (PEM).
  • cert: Optional certificate to use specified as a string in PEM format.
  • key_file: Optional key file to use (PEM).
  • key: Optional key to use specified as a string in PEM format.
  • watch_certs: If true, enables background reloading of certifcate files. Defaults to false.
  • watch_certs_poll_interval: If watch_certs is true, how often to check for changes. Defaults to 5 seconds.

• max_concurrent: The number of concurrent senders. A value of <=0 means the default which is 16.

• filter_tags: (Mandatory) Filter tags are used to classify the messages received, and so at least one tag must be specified.

  • botnet: A list of tags that indicate the event is filtered for the purposes of preventing botnet command and control connections.
  • malware: A list of tags that indicate the event is filtered for the purposes of preventing malware.
  • phishing: A list of tags that indicate the event is filtered for the purposes of preventing phishing.
  • blocklist: A list of tags that indicate the event is filtered because the user added the domain to their personal blocklist.
  • contentfilter: A list of tags that indicate the event is filtered because the user asked that category of content to be filtered.phishing

filter_tags:
    botnet:
        - tagA
        - tagB
    malware: [tagC, tagD]

• elasticsearch: A map containing parameters for configuring the connection to elasticsearch.
  • index: Name of the elasticsearch index to send events to.
  • add_date_to_index: If true, append the date to the index name when sending events, e.g. indexname-2006-12-23
  • addr: The address of the elasticsearch server.
  • user: The username to authenticate to elasticsearch
  • password: The password to authenticate to elasticsearch
  • cloud_id: Alternative auth method
  • api_key: Alternative auth method
  • ca_file: File path to CA certificate.
  • ca: Content of CA certificate, it has priority over CACertFile.

elasticsearch:
    index: my-forwarder-index
    add_date_to_index: true
    addr: http://elasticsearch:9200
    user: elastic
    password: ""