Dnstap

Example Configuration

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

Config

Input

Output

1[sources.my_source_id]
2type = "dnstap"
3max_frame_handling_tasks = 10_000
4socket_path = "/run/bind/dnstap.sock"
5socket_file_mode = 508
6max_frame_length = 102_400

1"Send a query to an authoritative BIND DNS server locally with following command:\n\n```bash\n\tnslookup host.example.com localhost\n```"

1[
2  {
3    "log": {
4      "dataType": "Message",
5      "dataTypeId": 1,
6      "messageType": "ClientQuery",
7      "messageTypeId": 5,
8      "requestData": {
9        "fullRcode": 0,
10        "header": {
11          "aa": false,
12          "ad": false,
13          "anCount": 0,
14          "arCount": 0,
15          "cd": false,
16          "id": 49653,
17          "nsCount": 0,
18          "opcode": 0,
19          "qdCount": 1,
20          "qr": 0,
21          "ra": false,
22          "rcode": 0,
23          "rd": true,
24          "tc": false
25        },
26        "question": [
27          {
28            "class": "IN",
29            "domainName": "host.example.com.",
30            "questionType": "A",
31            "questionTypeId": 1
32          }
33        ],
34        "rcodeName": "NoError",
35        "time": 1614781642516276700,
36        "timePrecision": "ns"
37      },
38      "responseAddress": "127.0.0.1",
39      "responsePort": 0,
40      "serverId": "ns1.example.com",
41      "serverVersion": "BIND 9.16.8",
42      "socketFamily": "INET",
43      "socketProtocol": "UDP",
44      "sourceAddress": "127.0.0.1",
45      "sourcePort": 52398,
46      "time": 1614781642516276700,
47      "timePrecision": "ns"
48    }
49  },
50  {
51    "log": {
52      "dataType": "Message",
53      "dataTypeId": 1,
54      "messageType": "ClientResponse",
55      "messageTypeId": 6,
56      "responseAddress": "127.0.0.1",
57      "responseData": {
58        "answers": [
59          {
60            "class": "IN",
61            "domainName": "host.example.com.",
62            "rData": "192.0.2.100",
63            "recordType": "A",
64            "recordTypeId": 1,
65            "ttl": 3600
66          }
67        ],
68        "authority": [
69          {
70            "class": "IN",
71            "domainName": "example.com.",
72            "rData": "ns1.example.com.",
73            "recordType": "NS",
74            "recordTypeId": 2,
75            "ttl": 86400
76          }
77        ],
78        "fullRcode": 0,
79        "header": {
80          "aa": true,
81          "ad": false,
82          "anCount": 1,
83          "arCount": 0,
84          "cd": false,
85          "id": 49653,
86          "nsCount": 1,
87          "opcode": 0,
88          "qdCount": 1,
89          "qr": 1,
90          "ra": true,
91          "rcode": 0,
92          "rd": true,
93          "tc": false
94        },
95        "question": [
96          {
97            "class": "IN",
98            "domainName": "host.example.com.",
99            "questionType": "A",
100            "questionTypeId": 1
101          }
102        ],
103        "rcodeName": "NoError",
104        "time": 1614781642516276700,
105        "timePrecision": "ns"
106      },
107      "responsePort": 0,
108      "serverId": "ns1.example.com",
109      "serverVersion": "BIND 9.16.8",
110      "socketFamily": "INET",
111      "socketProtocol": "UDP",
112      "sourceAddress": "127.0.0.1",
113      "sourceId": "421bce7d-b4e6-b705-6057-7039628a9847",
114      "sourcePort": 52398,
115      "time": 1614781642516276700,
116      "timePrecision": "ns"
117    }
118  }
119]

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

Config

Input

Output

1[sources.my_source_id]
2type = "dnstap"
3socket_send_buffer_size = 10_485_760
4socket_receive_buffer_size = 10_485_760
5socket_path = "/run/bind/dnstap.sock"
6socket_file_mode = 508

1"Send a dynamic update to an authoritative BIND DNS server locally with following command:\n\n```bash\n\tnsupdate <<EOF\n\tserver localhost\n\tupdate add h1.example.com 3600 a 192.0.2.110\n\tsend\n\tEOF\n```"

1[
2  {
3    "log": {
4      "dataType": "Message",
5      "dataTypeId": 1,
6      "messageType": "UpdateQuery",
7      "messageTypeId": 13,
8      "responseAddress": "127.0.0.1",
9      "responsePort": 0,
10      "serverId": "ns1.example.com",
11      "serverVersion": "BIND 9.16.8",
12      "socketFamily": "INET",
13      "socketProtocol": "UDP",
14      "sourceAddress": "127.0.0.1",
15      "sourcePort": 53141,
16      "time": 1599832089886768400,
17      "timePrecision": "ns",
18      "requestData": {
19        "fullRcode": 0,
20        "header": {
21          "adCount": 0,
22          "id": 47320,
23          "opcode": 5,
24          "prCount": 0,
25          "qr": 0,
26          "rcode": 0,
27          "upCount": 1,
28          "zoCount": 1
29        },
30        "rcodeName": "NoError",
31        "time": 1599832089886768400,
32        "timePrecision": "ns",
33        "update": [
34          {
35            "class": "IN",
36            "domainName": "h1.example.com.",
37            "rData": "192.0.2.110",
38            "recordType": "A",
39            "recordTypeId": 1,
40            "ttl": 3600
41          }
42        ],
43        "zone": {
44          "zClass": "IN",
45          "zName": "example.com.",
46          "zType": "SOA",
47          "zTypeId": 6
48        }
49      }
50    }
51  },
52  {
53    "log": {
54      "dataType": "Message",
55      "dataTypeId": 1,
56      "messageType": "UpdateResponse",
57      "messageTypeId": 14,
58      "responseAddress": "127.0.0.1",
59      "responsePort": 0,
60      "serverId": "ns1.example.com",
61      "serverVersion": "BIND 9.16.8",
62      "socketFamily": "INET",
63      "socketProtocol": "UDP",
64      "sourceAddress": "127.0.0.1",
65      "sourcePort": 53141,
66      "time": 1599832089890768400,
67      "timePrecision": "ns",
68      "responseData": {
69        "fullRcode": 0,
70        "header": {
71          "adCount": 0,
72          "id": 47320,
73          "opcode": 5,
74          "prCount": 0,
75          "qr": 1,
76          "rcode": 0,
77          "upCount": 0,
78          "zoCount": 1
79        },
80        "rcodeName": "NoError",
81        "time": 1599832089890768400,
82        "timePrecision": "ns",
83        "zone": {
84          "zClass": "IN",
85          "zName": "example.com.",
86          "zType": "SOA",
87          "zTypeId": 6
88        }
89      }
90    }
91  }
92]

Configuration Options

Required Options

socket_path(required)

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.

Type	Syntax	Default	Example
string	file_system_path		["/run/bind/dnstap.sock"]

type(required)

The component type. This is a required field for all components and tells Vector which component to use.

Type	Syntax	Default	Example
string	literal		["dnstap"]

Advanced Options

max_frame_length(optional)

Max dnstap frame length that the dnstap source can handle.

Type	Syntax	Default	Example
uint		102400

socket_file_mode(optional)

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.

Type	Syntax	Default	Example
uint			[511,492,508]

socket_receive_buffer_size(optional)

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

Type	Syntax	Default	Example
uint

socket_send_buffer_size(optional)

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

Type	Syntax	Default	Example
uint

raw_data_only(optional)

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

Type	Syntax	Default	Example
bool

How it Works

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

State

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

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.

Context

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