dnstap

Collect DNS logs from a dnstap-compatible server

status: beta role: daemon delivery: best effort egress: stream state: stateless output: log

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.

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.

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.