dnstap

Collect DNS logs from a dnstap-compatible server

status: beta role: daemon delivery: best effort acknowledgements: no egress: stream state: stateless output: log
Page source Edit this page

Configuration

Example configurations 

{
  "sources": {
    "my_source_id": {
      "type": "dnstap",
      "socket_path": "/run/bind/dnstap.sock",
      "socket_file_mode": 511
    }
  }
}
[sources.my_source_id]
type = "dnstap"
socket_path = "/run/bind/dnstap.sock"
socket_file_mode = 511

---
sources:
  my_source_id:
    type: dnstap
    socket_path: /run/bind/dnstap.sock
    socket_file_mode: 511

{
  "sources": {
    "my_source_id": {
      "type": "dnstap",
      "max_frame_length": 102400,
      "socket_path": "/run/bind/dnstap.sock",
      "socket_file_mode": 511,
      "socket_receive_buffer_size": null,
      "socket_send_buffer_size": null,
      "raw_data_only": null
    }
  }
}
[sources.my_source_id]
type = "dnstap"
max_frame_length = 102_400
socket_path = "/run/bind/dnstap.sock"
socket_file_mode = 511

---
sources:
  my_source_id:
    type: dnstap
    max_frame_length: 102400
    socket_path: /run/bind/dnstap.sock
    socket_file_mode: 511
    socket_receive_buffer_size: null
    socket_send_buffer_size: null
    raw_data_only: null

max_frame_length

optional uint
Max dnstap frame length that the dnstap source can handle.
default: 102400 (bytes)

raw_data_only

optional bool
Whether or not to write out raw dnstap frame data directly (to be encoded in Base64) without any parsing and formatting.
default: false

socket_file_mode

common optional uint
Unix file mode bits to be applied to server socket file as its designated file permissions. Note that the file mode value can be specified in any numeric format supported by TOML, but it’d be more intuitive to use an octal number. Also note that the value specified must be between 0o700 and 0o777.
Examples 
511
492
508

socket_path

required string file_system_path
Absolute path of server socket file to which the DNS server is configured to send dnstap data. The socket file will be created by dnstap source component automatically upon startup.
Examples 
"/run/bind/dnstap.sock"

socket_receive_buffer_size

optional uint
Set receive buffer size of server Unix socket if specified. No change to the default size if omitted.

Warning

System-wide setting of max socket receive buffer size (i.e. value of ‘/proc/sys/net/core/rmem_max’ on Linux) may need adjustment accordingly.

socket_send_buffer_size

optional uint
Set send buffer size of server Unix socket if specified. No change to the default size if omitted.

Warning

System-wide setting of max socket send buffer size (i.e. value of ‘/proc/sys/net/core/wmem_max’ on Linux) may need adjustment accordingly.

Outputs

<component_id>

Default output stream of the component. Use this component’s ID as an input to downstream transforms and sinks.

Output Data

Logs

Event

A single dnstap event.
Fields
dataType optional string literal
Dnstap event data type. Currently only ‘Message’ type is defined.
dataTypeId required uint
Numeric ID of dnstap event data type.
Examples
1
error optional string literal
Error message upon failure while parsing dnstap data.
Examples
Encountered error : Unexpected number of records in update section: 0
extraInfo optional string literal
Extra data for this event.
Examples
an arbitrary byte-string annotation
messageType optional string literal
Dnstap message type.
messageTypeId required uint
Numeric ID of dnstap message type.
Examples
6
rawData optional string literal
Raw dnstap binary data encoded in Base64. Presents only upon failures or option ‘raw_data_only’ is enabled.
Examples
ChBqYW1lcy11YnVudHUtZGV2EgtCSU5EIDkuMTYuNXKdAQgCEAEYASIEfwAAASoEfwAAATDRyAM4AFoNB2V4YW1wbGUDY29tAGCTvf76BW3evGImcmlihYQAAAEAAAABAAACaDIHZXhhbXBsZQNjb20AAAYAAcAPAAYAAQAADhAAPQtiZGRzLWRuc3RhcAAKcG9zdG1hc3RlcgJubwVlbWFpbAZwbGVhc2UAJADGPgAADhAAAAJYACeNAAAADhB4AQ==
requestData optional object
Request message data for DNS query/update.
responseAddress required string literal
The network address of the message responder.
Examples
192.0.2.18
fc00::200
responseData optional object
Response message data for DNS query/update.
responsePort optional uint
The transport port of the message responder.
Examples
60364
serverId optional string literal
DNS server identity.
Examples
ns1.example.com
serverVersion optional string literal
DNS server version.
Examples
BIND 9.16.8
socketFamily required string literal
The network protocol family of a socket. This specifies how to interpret ‘sourceAddress’/‘responseAddress’ fields.
Examples
INET
INET6
socketProtocol required string literal
The transport protocol of a socket. This specifies how to interpret ‘sourcePort’/‘responsePort’ fields.
Examples
UDP
TCP
sourceAddress required string literal
The network address of the message initiator.
Examples
192.0.2.8
fc00::100
sourcePort optional uint
The transport port of the message initiator.
Examples
52398
time required uint
The time at which the DNS message was sent or received. This is the number of time units (determined by ‘timePrecision’) since the UNIX epoch. For a DNS query/update request event, it’s same as request time. For a DNS query/update response event, it’s same as response time.
Examples
1614781642516276700
timePrecision required string literal
The time precision used by field ‘time’.
Examples
s
ms
us
ns
timestamp required string literal
The same time as of field “time”, but represented as an ISO 8601 date and time string (in UTC time zone).
Examples
2021-04-09T15:08:32.767098Z

Telemetry

Metrics

link

component_received_bytes_total

counter
The number of raw bytes accepted by this component from source origins.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
container_name optional
The name of the container from which the data originated.
file optional
The file from which the data originated.
host optional
The hostname of the system Vector is running on.
mode optional
The connection mode used by the component.
peer_addr optional
The IP from which the data originated.
peer_path optional
The pathname from which the data originated.
pid optional
The process ID of the Vector instance.
pod_name optional
The name of the pod from which the data originated.
uri optional
The sanitized URI from which the data originated.

component_received_event_bytes_total

counter
The number of event bytes accepted by this component either from tagged origins like file and uri, or cumulatively from other origins.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
container_name optional
The name of the container from which the data originated.
file optional
The file from which the data originated.
host optional
The hostname of the system Vector is running on.
mode optional
The connection mode used by the component.
peer_addr optional
The IP from which the data originated.
peer_path optional
The pathname from which the data originated.
pid optional
The process ID of the Vector instance.
pod_name optional
The name of the pod from which the data originated.
uri optional
The sanitized URI from which the data originated.

component_received_events_total

counter
The number of events accepted by this component either from tagged origins like file and uri, or cumulatively from other origins.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
container_name optional
The name of the container from which the data originated.
file optional
The file from which the data originated.
host optional
The hostname of the system Vector is running on.
mode optional
The connection mode used by the component.
peer_addr optional
The IP from which the data originated.
peer_path optional
The pathname from which the data originated.
pid optional
The process ID of the Vector instance.
pod_name optional
The name of the pod from which the data originated.
uri optional
The sanitized URI from which the data originated.

component_sent_event_bytes_total

counter
The total number of event bytes emitted by this component.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
host optional
The hostname of the system Vector is running on.
output optional
The specific output of the component.
pid optional
The process ID of the Vector instance.

component_sent_events_total

counter
The total number of events emitted by this component.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
host optional
The hostname of the system Vector is running on.
output optional
The specific output of the component.
pid optional
The process ID of the Vector instance.

events_in_total

counter
The number of events accepted by this component either from tagged origins like file and uri, or cumulatively from other origins. This metric is deprecated and will be removed in a future version. Use component_received_events_total instead.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
container_name optional
The name of the container from which the data originated.
file optional
The file from which the data originated.
host optional
The hostname of the system Vector is running on.
mode optional
The connection mode used by the component.
peer_addr optional
The IP from which the data originated.
peer_path optional
The pathname from which the data originated.
pid optional
The process ID of the Vector instance.
pod_name optional
The name of the pod from which the data originated.
uri optional
The sanitized URI from which the data originated.

events_out_total

counter
The total number of events emitted by this component. This metric is deprecated and will be removed in a future version. Use component_sent_events_total instead.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
host optional
The hostname of the system Vector is running on.
output optional
The specific output of the component.
pid optional
The process ID of the Vector instance.

lag_time_seconds

histogram
The difference between the timestamp recorded in each event and the time when it was ingested, expressed as fractional seconds.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
host optional
The hostname of the system Vector is running on.
pid optional
The process ID of the Vector instance.

parse_errors_total

counter
The total number of errors parsing metrics for this component.
host optional
The hostname of the system Vector is running on.
pid optional
The process ID of the Vector instance.

processed_bytes_total

counter
The number of bytes processed by the component.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
container_name optional
The name of the container from which the bytes originate.
file optional
The file from which the bytes originate.
host optional
The hostname of the system Vector is running on.
mode optional
The connection mode used by the component.
peer_addr optional
The IP from which the bytes originate.
peer_path optional
The pathname from which the bytes originate.
pid optional
The process ID of the Vector instance.
pod_name optional
The name of the pod from which the bytes originate.
uri optional
The sanitized URI from which the bytes originate.

processed_events_total

counter
The total number of events processed by this component. This metric is deprecated in place of using component_received_events_total and component_sent_events_total metrics.
component_id required
The Vector component ID.
component_kind required
The Vector component kind.
component_name required
Deprecated, use component_id instead. The value is the same as component_id.
component_type required
The Vector component type.
host optional
The hostname of the system Vector is running on.
pid optional
The process ID of the Vector instance.

Examples

Dnstap events for a pair of regular DNS query and response.

Given this event...
Send a query to an authoritative BIND DNS server locally with following command:

```bash
	nslookup host.example.com localhost
```
...and this configuration...
[sources.my_source_id]
type = "dnstap"
max_frame_length = 102_400
socket_file_mode = 508
socket_path = "/run/bind/dnstap.sock"
max_frame_handling_tasks = 10_000

---
sources:
  my_source_id:
    type: dnstap
    max_frame_length: 102400
    socket_file_mode: 508
    socket_path: /run/bind/dnstap.sock
    max_frame_handling_tasks: 10000

{
  "sources": {
    "my_source_id": {
      "type": "dnstap",
      "max_frame_length": 102400,
      "socket_file_mode": 508,
      "socket_path": "/run/bind/dnstap.sock",
      "max_frame_handling_tasks": 10000
    }
  }
}
...this Vector event is produced:
[{"log":{"dataType":"Message","dataTypeId":1,"messageType":"ClientQuery","messageTypeId":5,"requestData":{"fullRcode":0,"header":{"aa":false,"ad":false,"anCount":0,"arCount":0,"cd":false,"id":49653,"nsCount":0,"opcode":0,"qdCount":1,"qr":0,"ra":false,"rcode":0,"rd":true,"tc":false},"question":[{"class":"IN","domainName":"host.example.com.","questionType":"A","questionTypeId":1}],"rcodeName":"NoError","time":1614781642516276700,"timePrecision":"ns"},"responseAddress":"127.0.0.1","responsePort":0,"serverId":"ns1.example.com","serverVersion":"BIND 9.16.8","socketFamily":"INET","socketProtocol":"UDP","sourceAddress":"127.0.0.1","sourcePort":52398,"time":1614781642516276700,"timePrecision":"ns"}},{"log":{"dataType":"Message","dataTypeId":1,"messageType":"ClientResponse","messageTypeId":6,"responseAddress":"127.0.0.1","responseData":{"answers":[{"class":"IN","domainName":"host.example.com.","rData":"192.0.2.100","recordType":"A","recordTypeId":1,"ttl":3600}],"authority":[{"class":"IN","domainName":"example.com.","rData":"ns1.example.com.","recordType":"NS","recordTypeId":2,"ttl":86400}],"fullRcode":0,"header":{"aa":true,"ad":false,"anCount":1,"arCount":0,"cd":false,"id":49653,"nsCount":1,"opcode":0,"qdCount":1,"qr":1,"ra":true,"rcode":0,"rd":true,"tc":false},"question":[{"class":"IN","domainName":"host.example.com.","questionType":"A","questionTypeId":1}],"rcodeName":"NoError","time":1614781642516276700,"timePrecision":"ns"},"responsePort":0,"serverId":"ns1.example.com","serverVersion":"BIND 9.16.8","socketFamily":"INET","socketProtocol":"UDP","sourceAddress":"127.0.0.1","sourceId":"421bce7d-b4e6-b705-6057-7039628a9847","sourcePort":52398,"time":1614781642516276700,"timePrecision":"ns"}}]

Dnstap events for a pair of DNS update request and response.

Given this event...
Send a dynamic update to an authoritative BIND DNS server locally with following command:

```bash
	nsupdate <<EOF
	server localhost
	update add h1.example.com 3600 a 192.0.2.110
	send
	EOF
```
...and this configuration...
[sources.my_source_id]
type = "dnstap"
socket_file_mode = 508
socket_path = "/run/bind/dnstap.sock"
socket_receive_buffer_size = 10_485_760
socket_send_buffer_size = 10_485_760

---
sources:
  my_source_id:
    type: dnstap
    socket_file_mode: 508
    socket_path: /run/bind/dnstap.sock
    socket_receive_buffer_size: 10485760
    socket_send_buffer_size: 10485760

{
  "sources": {
    "my_source_id": {
      "type": "dnstap",
      "socket_file_mode": 508,
      "socket_path": "/run/bind/dnstap.sock",
      "socket_receive_buffer_size": 10485760,
      "socket_send_buffer_size": 10485760
    }
  }
}
...this Vector event is produced:
[{"log":{"dataType":"Message","dataTypeId":1,"messageType":"UpdateQuery","messageTypeId":13,"requestData":{"fullRcode":0,"header":{"adCount":0,"id":47320,"opcode":5,"prCount":0,"qr":0,"rcode":0,"upCount":1,"zoCount":1},"rcodeName":"NoError","time":1599832089886768400,"timePrecision":"ns","update":[{"class":"IN","domainName":"h1.example.com.","rData":"192.0.2.110","recordType":"A","recordTypeId":1,"ttl":3600}],"zone":{"zClass":"IN","zName":"example.com.","zType":"SOA","zTypeId":6}},"responseAddress":"127.0.0.1","responsePort":0,"serverId":"ns1.example.com","serverVersion":"BIND 9.16.8","socketFamily":"INET","socketProtocol":"UDP","sourceAddress":"127.0.0.1","sourcePort":53141,"time":1599832089886768400,"timePrecision":"ns"}},{"log":{"dataType":"Message","dataTypeId":1,"messageType":"UpdateResponse","messageTypeId":14,"responseAddress":"127.0.0.1","responseData":{"fullRcode":0,"header":{"adCount":0,"id":47320,"opcode":5,"prCount":0,"qr":1,"rcode":0,"upCount":0,"zoCount":1},"rcodeName":"NoError","time":1599832089890768400,"timePrecision":"ns","zone":{"zClass":"IN","zName":"example.com.","zType":"SOA","zTypeId":6}},"responsePort":0,"serverId":"ns1.example.com","serverVersion":"BIND 9.16.8","socketFamily":"INET","socketProtocol":"UDP","sourceAddress":"127.0.0.1","sourcePort":53141,"time":1599832089890768400,"timePrecision":"ns"}}]

How it works

Context

By default, the dnstap source augments events with helpful context keys.

Manipulate UDS Buffer Size

The dnstap source supports configuring the UDS buffer for both receiving and sending, which may be helpful for handling DNS traffic spikes more smoothly in high-usage scenarios in which performance is of paramount concern.

To configure the send/receive buffer size for the server UDS, set the socket_receive_buffer_size and socket_send_buffer_size parameters in the component’s configuration. Here’s an example:

[sources.my_dnstap_source]
type = "dnstap"
socket_receive_buffer_size = 10_485_760
socket_send_buffer_size = 10_485_760
# Other configs

For the buffer size settings to take effect, you need to ensure that the system-wide settings for send/receive buffer sizes (i.e. the values of /proc/sys/net/core/rmem_max and /proc/sys/net/core/wmem_max on Linux) are large enough.

Server Unix Domain Socket (UDS)

The dnstap source receives dnstap data through a Unix Domain Socket (aka UDS). The path of the UDS must be explicitly specified in the source’s configuration.

Upon startup, the dnstap source creates a new server UDS at the specified path. If the path of UDS is already in use, Vector automatically deletes it before creating a new path.

The default permissions of the UDS are determined by the current umask value. To customize it to allow the local BIND server to send dnstap data to the UDS, you can specify the desired UDS permissions (for example the file mode) explicitly in the dnstap source configuration. To set its permissions to 0774, for example, add the socket_file_mode option:

[sources.my_dnstap_source]
type = "dnstap"
socket_file_mode: 0o774
# Other configs

Using a remote BIND server

While the dnstap source can create server UDS paths only on the local machine, you can also use it with remote BIND servers by forwarding the server UDS from the machine Vector is running on to the remote BIND server (for example via SSH) once Vector starts. Make sure that the Unix domain sockets on both the local and remote machines have appropriate permissions set.

State

This component is stateless, meaning its behavior is consistent across each input.
Sidebar