Skip to content

Latest commit

 

History

History
193 lines (154 loc) · 6.57 KB

configuration.md

File metadata and controls

193 lines (154 loc) · 6.57 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 in multiplexer mode 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.

You can find the global settings below

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"

Worker

The interval-monitor in second(s) is used to count every XX second the number of in/out packets.

The buffer-size settings enable to adjust the size of the buffer before discard additional packets. If you encounter the error message buffer is full, xxx packet(s) dropped, consider increasing this parameter to prevent message drops.

global:
  worker:
    interval-monitor: 10
    buffer-size: 4096

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
  • peer-name: hostname or ip address of the dnstap sender
  • version: dnstap version
  • extra: dnstap extra as string
  • operation: dnstap operation
  • policy-rule: dnstap policy rule
  • policy-type: dnstap policy type
  • policy-action: dnstap policy action
  • policy-match: dnstap policy match
  • policy-value: dnstap policy value
  • query-zone: dnstap query zone
  • 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 in bytes
  • length-unit: the length of the query or reply in bytes with unit (b)
  • qtype: dns query type
  • qclass: dns query class
  • qname: dns query name
  • 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-unit qname qtype latency ttl"
  text-format-delimiter: " "
  text-format-splitter: " "
  text-format-boundary: "\""
  text-jinja: ""

If you require a output format like CSV, the delimiter can be configured with the text-format-delimiter option. The default separator is [space]. text-format can contain raw text enclosed by curly braces, eg

	text-format: "timestamp-rfc3339ns identity operation rcode queryip queryport qname qtype {DNSTAP}"

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

If you want a more flexible format, you can use the text-jinja setting Example to enable output similiar to dig style:

text-jinja: |+
    ;; Got {% if dm.DNS.Type == "QUERY" %}query{% else %}answer{% endif %} from {{ dm.NetworkInfo.QueryIP }}#{{ dm.NetworkInfo.QueryPort }}:
    ;; ->>HEADER<<- opcode: {{ dm.DNS.Opcode }}, status: {{ dm.DNS.Rcode }}, id: {{ dm.DNS.ID }}
    ;; flags: {{ dm.DNS.Flags.QR | yesno:"qr ," }}{{ dm.DNS.Flags.RD | yesno:"rd ," }}{{ dm.DNS.Flags.RA | yesno:"ra ," }}; QUERY: {{ dm.DNS.QuestionsCount }}, ANSWER: {{ dm.DNS.DNSRRs.Answers | length }}, AUTHORITY: {{ dm.DNS.DNSRRs.Nameservers | length }}, ADDITIONAL: {{ dm.DNS.DNSRRs.Records | length }}
    
    ;; QUESTION SECTION:
    ;{{ dm.DNS.Qname }}		{{ dm.DNS.Qclass }}	{{ dm.DNS.Qtype }}

    ;; ANSWER SECTION: {% for rr in dm.DNS.DNSRRs.Answers %}
    {{ rr.Name }}		{{ rr.TTL }} {{ rr.Class }} {{ rr.Rdatatype }} {{ rr.Rdata }}{% endfor %}

    ;; WHEN: {{ dm.DNSTap.Timestamp }}
    ;; MSG SIZE  rcvd: {{ dm.DNS.Length }}

Pid file

Set path to create DNS-collector PID. By default, this settings is empty.

global:
  pid-file: "/path/to/your/pidfile.pid"

Telemetry

Enable and configure telemetry

global:
  telemetry:
    enabled: true
    web-path: "/metrics"
    web-listen: ":9165"
    prometheus-prefix: "dnscollector_exporter"
    tls-support: false
    tls-cert-file: ""
    tls-key-file: ""
    client-ca-file: ""
    basic-auth-enable: false
    basic-auth-login: admin
    basic-auth-pwd: changeme