dnstap

The DNSTAP source collects DNS query and response logs from servers that support the dnstap protocol. It listens for incoming DNSTAP frames over TCP or Unix domain sockets and emits decoded DNS events into the telemetry pipeline.

This source is commonly used in environments where DNS observability, security analysis, and traffic inspection are required, such as enterprise networks, ISPs, and security-focused deployments.

The DNSTAP source operates as a passive listener. A DNSTAP-compatible DNS server actively pushes DNS events to the configured socket endpoint.

Collected events may include:

Events are processed in real time and forwarded downstream without persistent state.

The source supports two socket types:

The socket mode determines which configuration options are applicable.

Defines the socket address to listen on when using TCP mode.

The address must include a port number. Alternatively, systemd socket activation can be used to inherit an existing socket.

Relevant when:

Defines the absolute filesystem path of the Unix domain socket used to receive DNSTAP data.

The socket file is created automatically if it does not exist.

Relevant when:

Limits the maximum number of concurrent TCP connections.

This prevents resource exhaustion in high-throughput or untrusted environments.

Defines the maximum lifetime of a single TCP connection.

Connections exceeding this duration are closed automatically, which can help with load balancing and long-lived connection management.

Controls TCP keepalive behavior for idle connections.

This helps detect broken connections and release resources proactively.

Specifies how long the source waits for active connections to close gracefully during shutdown before forcefully terminating them.

Defines the maximum accepted DNSTAP frame size.

Frames exceeding this limit are discarded to protect the system from oversized payloads.

Limits the number of DNSTAP frames that can be processed concurrently.

This setting directly impacts throughput and resource usage.

Enables concurrent processing of DNSTAP frames.

When enabled, multiple frames can be decoded and processed in parallel to improve performance under high load.

When enabled, DNSTAP frames are not parsed or decoded.

Instead, the raw frame payload is attached to each event as a base64-encoded field. This mode is useful for:

Controls whether all DNS hostnames are normalized to lowercase.

Enabling this improves consistency and simplifies downstream querying and aggregation.

Defines a list of allowed client IP networks using CIDR notation.

Only connections originating from these networks are accepted.

Relevant when:

Overrides the field name used to attach the source host information to each log event.

The value added corresponds to the socket address or socket path.

Overrides the field name used to record the peer’s port number.

Setting this value to an empty string suppresses port metadata entirely.

Relevant when:

Controls the size of the receive buffer for each TCP connection.

Adjusting this may improve performance under high-throughput conditions.

Define receive and send buffer sizes for Unix domain sockets.

System-wide kernel buffer limits may need adjustment when increasing these values.

Relevant when:

Specifies file permission bits applied to the Unix domain socket.

This controls which users and processes are allowed to send DNSTAP data to the source.

Enables TLS encryption and client authentication for TCP connections.

TLS can be used to:

When enabled, TLS verification ensures:

Disabling verification significantly weakens security and should only be done in controlled environments.