1. Output formats
2. ISC BIND querylog format
   1. Querylog enhancements
   2. Supported message types
   3. Syslog envelopes
   4. Query message
   5. Response message
   6. Error message
3. JSON format
   1. Top-level envelope
   2. Query message
   3. Response message
   4. Error message
4. dnstap format
   1. Overview
   2. ETW client query message
   3. ETW client response message
   4. ETW resolver query message
   5. ETW resolver response message

Output formats

DnsStream supports three output DNS message formats controlled by the message-format directive in dnsstream.conf:

DnsStream uses dnstap as its internal message representation. Windows ETW events are converted into equivalent dnstap message types before entering the processing pipeline. dnstap messages received from UNIX domain sockets are accepted and queued unchanged.

When message-format dnstap is configured, DnsStream forwards dnstap messages without modification. Any dnstap message type can be accepted and forwarded.

ISC BIND querylog format

Querylog enhancements

DnsStream’s querylog output is based on the ISC BIND query log format, extended with a response: keyword and inline answer records for response messages. Additionally errors: to report errors relating to processing DNS messages, are also emitted.

Querylog messages are delivered as the syslog message body in both BSD syslog and RFC 5424 delivery modes.

The querylog format has two variants controlled by message-querylog-format in dnsstream.conf:

• Standard - the core BIND querylog fields only.
• Extended - standard fields plus a size, transaction ID and domain field (for query name and all record names in response type events).

Both standard and extended formats are documented for each relevant event type.

Supported message types

DnsStream generates querylog output from the following dnstap message types:

• AUTH_QUERY
• AUTH_RESPONSE
• CLIENT_QUERY
• CLIENT_RESPONSE
• RESOLVER_QUERY
• RESOLVER_RESPONSE
• FORWARDER_QUERY
• FORWARDER_RESPONSE
• STUB_QUERY
• STUB_RESPONSE
• TOOL_QUERY
• TOOL_RESPONSE

Each message type uses the same query and response schemas documented below, with the DNS role appearing in the querylog messages adjusted for the dnstap message type (i.e. queries: client vs queries: resolver):

All other dnstap message types are discarded when generating querylog output.

Syslog envelopes

DnsStream delivers messages wrapped in a syslog envelope when message-format querylog is set. Two envelope formats are available: BSD syslog (RFC 3164) and structured syslog (RFC 5424).

The BSD syslog (RFC 3164) envelope is the older of the two formats and is supported by virtually every syslog receiver. It has no version field, uses a locale-dependent timestamp with no year or timezone, and carries the PID in bracket notation attached to the app name.

<30>Mar 23 19:40:44 WIN-4L04FD5AKGL dnsstream[8296]: <message>

RFC 5424 is the modern structured syslog format. It adds a version field, a timezone-aware ISO 8601 timestamp, a message ID field, and a structured data section. DnsStream sets both the message ID and structured data fields to the nil value -, carrying all message data in the message body.

<30>1 2000-01-01T19:00:00.23123Z windows2025 dnsstream 6824 - - <message>

The same priority value, which defaults to <30>, is used for all DnsStream messages. For reference:

This can changed in the dnsstream.conf configuration file using the message-syslog-priority directive.

Query message

The query schema is used for:

• AUTH_QUERY
• CLIENT_QUERY
• RESOLVER_QUERY
• FORWARDER_QUERY
• STUB_QUERY
• TOOL_QUERY

The only difference is the role keyword immediately following queries:.

Full message - with message-syslog-format rfc5424 and message-querylog-format standard set:

<30>1 2000-01-01T19:00:00.23123Z windows2025 dnsstream 6824 - - queries: client 192.168.68.164#61776: query: telemity.com. IN A + (192.168.68.162)

Full message - with message-syslog-format rfc5424 and message-querylog-format extended set:

<30>1 2000-01-01T19:00:00.23123Z windows2025 dnsstream 6824 - - queries: resolver 192.168.68.164#61776 %1085: query: telemity.com. [telemity.com.] IN A + (192.168.68.162 32b)

Full message - with message-syslog-format bsd and message-querylog-format standard set:

<30>Mar 23 19:40:44 WIN-4L04FD5AKGL dnsstream[8296]: queries: forwarder 192.168.68.164#61750: query: telemity.com. IN A + (192.168.68.162)

Standard fields are always included, extended fields are only present when message-querylog-format extended is set.

The flags object reflects the DNS header flags present in the query. Flags are concatenated without separators. The following flags are currently included:

Response message

The response schema is used for:

• AUTH_RESPONSE
• CLIENT_RESPONSE
• RESOLVER_RESPONSE
• FORWARDER_RESPONSE
• STUB_RESPONSE
• TOOL_RESPONSE

The only difference is the role keyword immediately following queries:.

Full message - with message-syslog-format rfc5424 and message-querylog-format standard set:

<30>1 2000-01-01T19:00:00.23123Z windows2025 dnsstream 6824 - - queries: client 192.168.68.164#61776: response: www.telemity.com. IN A + (192.168.68.162) NOERROR; www.telemity.com. 600 IN CNAME telemity.com.; telemity.com. 600 IN A 20.47.114.0

Full message - with message-syslog-format rfc5424 and message-querylog-format extended set:

<30>1 2000-01-01T19:00:00.23123Z windows2025 dnsstream 6824 - - queries: resolver 192.168.68.164#61776 %1085: response: www.telemity.com. [telemity.com.] IN A + (192.168.68.162 89b) NOERROR; www.telemity.com. [telemity.com.] 600 IN CNAME telemity.com.; telemity.com. [telemity.com.] 600 IN A 20.47.114.0

Full message - with message-syslog-format bsd and message-querylog-format standard set:

<30>Mar 23 19:40:44 WIN-4L04FD5AKGL dnsstream[8296]: queries: forwarder 192.168.68.164#61776: response: www.telemity.com. IN A + (192.168.68.162) NOERROR; www.telemity.com. 600 IN CNAME telemity.com.; telemity.com. 600 IN A 20.47.114.0

Standard fields are always included, extended fields are only present when message-querylog-format extended is set.

The flags object reflects the DNS header flags present in the response. Flags are concatenated without separators. The following flags are currently included:

Each record in the answer-record field follows standard DNS presentation format: name ttl class type data. For extended querylog format, an additional domain field is present after name. All records are preceeded with ; (semicolon and space) which allows parsing using regex groupings and determining the presence of answer records easier. The example shows a two-record CNAME chain in extended format:

; www.telemity.com. [telemity.com.] 600 IN CNAME telemity.com.; telemity.com. [telemity.com.] 600 IN A 20.47.114.0

FQDNs in name and data always end with a trailing dot unless message-fqdn-format without-trailing-dot is set.

The data field of each DNS record is always a string in DNS presentation format, i.e. what you might find in a DNS zone file in plain text format. The format is determined by rrtype, e.g..

Unknown record types are preserved as hex-encoded data and are never silently dropped. If DnsStream encounters an unfamiliar rrtype, the raw bytes are always available in data using the format \# <length> <hex-encoding>.

Error message

Generated when DnsStream receives a message which contains a DNS packet it cannot parse. Captures the raw packet for downstream analysis and includes an error description.

Error messages are delivered to the same forwarding target as DNS messages, in the same querylog format. This is embedded in the same configured Syslog envelope, and can be parsed and routed by the same pipeline. It is distinguished from other message by the errors: keyword in place of queries:.

Full message - with message-syslog-format rfc5424 set:

<28>1 2000-01-01T19:00:00.23123Z windows2025 dnsstream 6824 - - errors: Read DNS message failed: Read uint16_t failed: Offset 8 + 2 is out of bounds for data of 9 bytes: client 192.168.68.164#54812: server 192.168.68.100: packet \# 9 A51500200001000000

Full message - with message-syslog-format bsd set:

<28>Mar 23 19:40:44 WIN-4L04FD5AKGL dnsstream[8296]: errors: Read DNS message failed: Read uint16_t failed: Offset 8 + 2 is out of bounds for data of 9 bytes: client 192.168.68.164#54812: server 192.168.68.100: packet \# 9 A51500200001000000

JSON format

Top-level envelope

DnsStream’s JSON output sends newline-delimited JSON objects (NDJSON) over a persistent TCP connection. Each message is a single JSON object on a single line, terminated by \n. There is no framing, no length prefix, and no enclosing array - each line is a complete, independently parseable message.

{"timestamp":"2000-01-01T19:00:00.23123Z","host":"windows2025",...}\n

Every DnsStream JSON message shares the same top-level structure.

{
  "timestamp": "2000-01-01T19:00:00.23123Z",
  "host":      "windows2025",
  "schema":    1,
  "type":      "client-response",
  "data":      { ... }
}

The following message types are currently defined for JSON output:

• client-query
• client-response
• resolver-query
• resolver-response
• forwarder-query
• forwarder-response
• stub-query
• stub-response
• tool-query
• tool-response
• invalid-message

All query and response message types share the same schemas as client-query and client-response.

All other dnstap message types are discarded when generating JSON output.

Query message

Generated for DNS query messages. Contains question section fields only - no response data is present.

This schema is used for:

• client-query
• resolver-query
• forwarder-query
• stub-query
• tool-query

Only the top-level type field differs.

{
  "timestamp": "2000-01-01T19:00:00.23123Z",
  "host":      "windows2025",
  "schema":    1,
  "type":      "client-query",
  "data": {
    "client":  "192.168.68.164",
    "server":  "192.168.68.162",
    "port":    61776,
    "proto":   "UDP",
    "size":    32,
    "txid":    1085,
    "flags": {
      "rd": true
    },
    "qname":   "www.telemity.com.",
    "qdomain": "telemity.com.",
    "qclass":  "IN",
    "qtype":   "A"
  }
}

The following data fields are included in addition to the Top-level envelope fields:

The flags object reflects the DNS header flags present in the query.

Response message

Generated for DNS response messages. Extends query fields with the server’s answer - the response code and the full answer, authority, and additional sections.

This schema is used for:

• client-response
• resolver-response
• forwarder-response
• stub-response
• tool-response

Only the top-level type field differs.

{
  "timestamp": "2000-01-01T19:00:00.23123Z",
  "host":      "windows2025",
  "schema":    1,
  "type":      "client-response",
  "data": {
    "client":  "192.168.68.164",
    "server":  "192.168.68.162",
    "port":    61776,
    "proto":   "UDP",
    "size":    89,
    "txid":    1085,
    "flags": {
      "rd": true,
      "ra": true,
      "aa": false,
      "tc": false
    },
    "qname":   "www.telemity.com.",
    "qdomain": "telemity.com.",
    "qclass":  "IN",
    "qtype":   "A",
    "rcode":   "NOERROR",
    "answers": [
      {
        "name":    "www.telemity.com.",
        "domain":  "telemity.com.",
        "ttl":     600,
        "rrclass": "IN",
        "rrtype":  "CNAME",
        "data":    "telemity.com."
      },
      {
        "name":    "telemity.com.",
        "domain":  "telemity.com.",
        "ttl":     600,
        "rrclass": "IN",
        "rrtype":  "A",
        "data":    "20.47.114.0"
      }
    ],
    "authority":  [],
    "additional": []
  }
}

The following data fields are included in addition to the Top-level envelope fields:

The flags object reflects the DNS header flags present in the response.

DNS records in answers, authority, and additional are objects which define one complete DNS record:

Trailing dots on domain names are present unless message-fqdn-format without-trailing-dot is set in dnsstream.conf, in which case they are omitted from all FQDN values throughout the message.

The data field of each DNS record is always a string in DNS presentation format, i.e. what you might find in a DNS zone file in plain text format. The format is determined by rrtype, e.g..

Unknown record types are preserved as hex-encoded data and are never silently dropped. If DnsStream encounters an unfamiliar rrtype, the raw bytes are always available in data using the format \# <length> <hex-encoding>.

Error message

Generated when DnsStream receives a message which contains a DNS packet it cannot parse. Captures the raw packet for downstream analysis and includes an error description.

{
  "timestamp": "2000-01-01T19:00:00.23123Z",
  "host":      "windows2025",
  "schema":    1,
  "type":      "error",
  "data": {
    "client":  "192.168.68.164",
    "server":  "192.168.68.162",
    "port":    54812,
    "size":    9,
    "text":   "Read DNS message failed: Read uint16_t failed: Offset 8 + 2 is out of bounds for data of 9 bytes",
    "packet":  "0a1b2c3d4e5f0a1b2c"
  }
}

The following data fields are included in addition to the Top-level envelope fields:

dnstap format

Overview

When message-format dnstap is set, DnsStream emits dnstap messages over Frame Streams (fstrm) using TCP or TLS transport. DnsStream uses dnstap as its internal message representation.

For Linux, inbound dnstap messages are accepted and forwarded unchanged.

For Windows, ETW events are converted into dnstap messages before entering the processing pipeline and are then forwarded as dnstap messages.

The ETW client query message, ETW client response message, ETW resolver query message and ETW resolver response message sections identify how the ETW event fields are mapped to dnstap message fields.

Forwarded dnstap messages are transported using Frame Streams (fstrm) over plaintext TCP or TLS-encrypted TCP. The transport is configured using the standard forwarder directive and optional TLS parameters in dnsstream.conf.

DnsStream supports both fstrm modes:

The mode is controlled by fstrm-mode option on the forwarder directive, the default should suffice unless there is a specific requirement for unidirectional.

For dnstap messages created from Windows ETW events, when converting to dnstap DnsStream optionally populates the dnstap identity, version and extra fields using options on the listener etw directive.

ETW client query message

The Message structure of the generated CLIENT_QUERY dnstap message contains the following fields:

ETW client response message

The Message structure of the generated CLIENT_RESPONSE dnstap message contains the following fields:

ETW resolver query message

The Message structure of the generated RESOLVER_QUERY dnstap message contains the following fields:

ETW resolver response message

The Message structure of the generated RESOLVER_RESPONSE dnstap message contains the following fields: