dnstap

Collect DNS logs from a dnstap-compatible server

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

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.

socket_path

required string

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.

socket_receive_buffer_size

optional uint

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

socket_send_buffer_size

optional uint

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

Output

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

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

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

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

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

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

events_in_total

counter

The number of events accepted by this component either from tagged origin like file and uri, or cumulatively from other origins.

component_kind required

The Vector component kind.

component_name required

The Vector component name.

component_type required

The Vector component type.

container_name optional

The name of the container from which the event originates.

file optional

The file from which the event originates.

mode optional

The connection mode used by the component.

peer_addr optional

The IP from which the event originates.

peer_path optional

The pathname from which the event originates.

pod_name optional

The name of the pod from which the event originates.

uri optional

The sanitized URI from which the event originates.

events_out_total

counter

The total number of events emitted by this component.

component_kind required

The Vector component kind.

component_name required

The Vector component name.

component_type required

The Vector component type.

parse_errors_total

counter

The total number of errors parsing metrics for this component.

processed_bytes_total

counter

The number of bytes processed by the component.

component_kind required

The Vector component kind.

component_name required

The Vector component name.

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.

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.

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 events_in_total and events_out_total metrics.

component_kind required

The Vector component kind.

component_name required

The Vector component name.

component_type required

The Vector component type.

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.