Skip to content

Latest commit

 

History

History
164 lines (130 loc) · 5.03 KB

configuration.md

File metadata and controls

164 lines (130 loc) · 5.03 KB
Raw

DNS-collector - Configuration Guide

The configuration of DNS-collector is done through one yaml file named config.yml. When the DNS-collector starts, it will look for the config.yml from the current working directory.

A typically configuration would have one or more collector to receive DNS traffic, and severals loggers to process the incoming traffics. You can take a look to the list of config examples.

Global

Trace

Logs can be enable to have more informations like debug, errors messages generated by the application

Options:

  • verbose: (boolean) debug informations, if turned on, log some applications messages
  • filename: (string) filename is the file to write logs to.
  • max-size: (integer) maximum size in megabytes of the log file it gets rotated
  • max-backups: (integer) maximum number of old log files to retain
  • log-malformed: (boolean) log malformed packet
global:
  trace:
    verbose: true
    log-malformed: false
    filename: ""
    max-size: 10
    max-backups: 10

Example:

INFO: 2022/06/25 20:54:18.173239 main - version 0.0.0
INFO: 2022/06/25 20:54:18.173271 main - config loaded...
INFO: 2022/06/25 20:54:18.173277 main - starting dns-collector...
....
INFO: 2022/06/25 20:54:18.174256 [dtap] dnstap collector - running in background...
INFO: 2022/06/25 20:54:18.174286 [dtap] dnstap collector - is listening on [::]:6000

Server Identity

Set the server identity name. The hostname will be used if empty

global:
  server-identity: "dns-collector"

Custom text format

The text format can be customized with the following directives.

Default directives:

  • timestamp-rfc3339ns: timestamp rfc3339 format, with nano support
  • timestamp-unixms: unix timestamp with ms support
  • timestamp-unixus: unix timestamp with us support
  • timestamp-unixns: unix timestamp with nano support
  • localtime: local time
  • identity: dnstap identity
  • version: dnstap version
  • operation: dnstap operation
  • opcode: dns opcode (integer)
  • rcode: dns return code
  • queryip: dns query ip
  • queryport: dns query port
  • responseip: dns response ip
  • responseport: dns response port
  • id: dns id
  • family: ip protocol version INET or INET6
  • protocol: protocol UDP, TCP
  • length: the length of the query or reply
  • qtype: dns qtype
  • qname: dns qname
  • latency: computed latency between queries and replies
  • answercount: the number of answer
  • ttl: answer ttl, only the first one
  • answer: rdata answer, only the first one, prefer to use the JSON format if you wamt all answers
  • malformed: malformed dns packet, integer value 1/0
  • qr: query or reply flag, string value Q/R
  • tc: flag truncated response
  • aa: flag authoritative answer
  • ra: flag recursion available
  • ad: flag authenticated data
  • df: flag when ip defragmented occured
  • tr: flag when tcp reassembled occured
  • edns-csubnet: display client subnet info
global:
  text-format: "timestamp-rfc3339ns identity qr operation rcode queryip queryport family protocol length qname qtype latency ttl"
  text-format-delimiter: " "
  text-format-boundary: "\""

If you require a format like CSV, the delimiter can be configured with the text-format-delimiter option. The default separator is [space].

Output example:

2023-04-08T18:27:29.268465Z unbound CLIENT_QUERY NOERROR 127.0.0.1 39028 IPv4 UDP 50b google.fr A 0.000000
2023-04-08T18:27:29.268575Z unbound FORWARDER_QUERY NOERROR 0.0.0.0 20817 IPv4 UDP 38b google.fr A 0.000000
2023-04-08T18:27:29.278929Z unbound FORWARDER_RESPONSE NOERROR 0.0.0.0 20817 IPv4 UDP 54b google.fr A 0.000000
2023-04-08T18:27:29.279039Z unbound CLIENT_RESPONSE NOERROR 127.0.0.1 39028 IPv4 UDP 54b google.fr A 0.000000

Multiplexer

The dns collector can be configured with multiple loggers and collectors at the same time.

You must defined the list of

  • collectors: list of running inputs
  • loggers: list of running outputs
  • routes: routing definition

If you want apply some modifications in traffic, you can do that with transformers. Transformers can be applied on collectors or loggers.

Collectors

List of supported collectors

multiplexer:
  collectors: 
    - name: <collector_name>
      .....

Loggers

List of supported loggers

multiplexer:
  loggers: 
    - name: <logger_name>
      ...

Routes

Then defines the routing to use between all of them according to the name. You can connect one collector to multiple loggers and you can also connect multiple collectors to the same logger.

multiplexer:
  routes: ...
    - from: [ list of collectors by name ]
      to: [ list of loggers by name ]