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
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 messagesfilename
: (string) filename is the file to write logs to.max-size
: (integer) maximum size in megabytes of the log file it gets rotatedmax-backups
: (integer) maximum number of old log files to retainlog-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
Set the server identity name. The hostname will be used if empty
global:
server-identity: "dns-collector"
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 warning message buffer is full, xxx packet(s) dropped, consider increasing this parameter to prevent message drops.
global:
worker:
interval-monitor: 10
buffer-size: 8192
The text format can be customized with the following directives.
Default directives:
timestamp-rfc3339ns
: timestamp rfc3339 format, with nano supporttimestamp-unixms
: unix timestamp with ms supporttimestamp-unixus
: unix timestamp with us supporttimestamp-unixns
: unix timestamp with nano supportlocaltime
: local timeidentity
: dnstap identitypeer-name
: hostname or ip address of the dnstap senderversion
: dnstap versionextra
: dnstap extra as stringoperation
: dnstap operationpolicy-rule
: dnstap policy rulepolicy-type
: dnstap policy typepolicy-action
: dnstap policy actionpolicy-match
: dnstap policy matchpolicy-value
: dnstap policy valuequery-zone
: dnstap query zoneopcode
: dns opcode (integer)rcode
: dns return codequeryip
: dns query ipqueryport
: dns query portresponseip
: dns response ipresponseport
: dns response portid
: dns idfamily
: ip protocol version INET or INET6protocol
: protocol UDP, TCPlength
: the length of the query or reply in byteslength-unit
: the length of the query or reply in bytes with unit (b
)qtype
: dns query typeqclass
: dns query classqname
: dns query namelatency
: computed latency between queries and repliesqdcount
: the number of questionancount
: the number of answerarcount
: the number of additionnal answernscount
: the number of nameserverttl
: answer ttl, only the first oneanswer
: rdata answer, only the first one, prefer to use the JSON format if you wamt all answersmalformed
: malformed dns packet, integer value 1/0qr
: query or reply flag, string value Q/Rtc
: flag truncated responseaa
: flag authoritative answerra
: flag recursion availablead
: flag authenticated datadf
: flag when ip defragmented occuredtr
: flag when tcp reassembled occurededns-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.QdCount }}, ANSWER: {{ dm.DNS.AnCount }}, AUTHORITY: {{ dm.DNS.NsCount }}, ADDITIONAL: {{ dm.DNS.ArCount }}
;; 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 }}
Set path to create DNS-collector PID. By default, this settings is empty.
global:
pid-file: "/path/to/your/pidfile.pid"
Enable and configure telemetry
global:
telemetry:
enabled: false
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