DnsStream is a lightweight software agent developed by Telemity that collects DNS telemetry from Windows and Linux DNS infrastructure and forwards structured messages to SIEM, observability, and log management platforms.
DnsStream operates as a passive observer. It does not participate in DNS resolution and has no impact on DNS service operation. On Windows it consumes ETW events generated by the DNS Server service. On Linux it receives dnstap messages generated by the local DNS server.
DnsStream is the collection layer in the telemetry stack. It does not perform detection, analysis, or enforcement. Its job is to deliver complete, high-fidelity DNS message data to the platforms where those functions already operate.
Three principles govern every aspect of DnsStream’s design.
Telemetry collection is a distinct concern. Detection, correlation, and analytics belong in the SIEM. Bundling detection logic into a telemetry agent creates fragility, opacity, and lock-in. DnsStream collects and forwards - nothing else.
Production systems come first. DnsStream is deployed on DNS infrastructure. DNS is critical infrastructure. Every design decision is evaluated against a single question: what is the cost to production? The answers to that question produced the native telemetry architecture, the in-memory pipeline, the fixed memory footprint, and the passive observer model.
The data that leaves should be complete. Partial telemetry is worse than its absence in some respects - it creates the illusion of coverage while leaving real gaps. DnsStream fully decodes DNS messages meaning that every response message includes the complete answer section, all resource records, and all TTL values.
DnsStream captures DNS telemetry using the native telemetry source provided by the DNS platform.
On Windows, DnsStream subscribes to the Microsoft-Windows-DNSServer ETW provider and receives DNS query and response messages directly from the DNS Server service. Messages are delivered to DnsStream’s callback in kernel-buffered memory - there is no disk I/O, no polling, and no shared log files in the capture path.
The Windows DNS Server ETW provider is the only mechanism that gives access to DNS messages as the DNS service generates them - after DNS parsing is complete, before any network activity. This gives ETW-based capture several structural advantages over the alternatives:
Versus DNS debug logging. The debug log writes to disk synchronously at high volume, produces unstructured text requiring fragile parsing, and was designed as a troubleshooting tool rather than a production telemetry pipeline. ETW has none of these characteristics.
Versus packet capture. Network-layer capture typically requires a kernel-level capture driver (Npcap, WinPcap, or equivalent) - or at the very least a network interface permanently in promiscuous mode which also requires permanently elevated permissions - on the production DNS server which introduces kernel attack surface. This requires IPv4, IPv6, UDP and TCP reassembly and decoding work that the network stack and DNS service has already done internally.
Versus other ETW consumers. Other agents that consume the DNS Server ETW provider don’t parse the DNS packet data provided with each ETW event, only capturing data like query name, type, and client address while omitting the response payload - answer records, TTL values, authority and additional sections. DnsStream fully decodes DNS packets and includes this data.
On Linux, DnsStream receives dnstap messages over a local UNIX domain socket and decouples DNS message production from downstream forwarding using a configurable in-memory ring buffer. This allows temporary collector or network outages to be absorbed without immediately dropping telemetry, while also providing transport options including JSON, querylog and dnstap over TCP or TLS.
DnsStream supports dnstap producers including BIND, Unbound, Knot DNS, PowerDNS, CoreDNS, dnsdist and other DNS software capable of emitting dnstap over Frame Streams. As dnstap messages are generated by the DNS application itself, DnsStream receives structured DNS messages without requiring packet capture, traffic reconstruction, protocol decoding, or access to network interfaces.
DnsStream can replace multi-stage dnstap pipelines with a single lightweight agent that receives, transforms, and forwards DNS telemetry wherever it needs to go.
All processing between telemetry capture and network transmission occurs in memory. DnsStream does not write message data to disk.
Receive. DnsStream receives DNS telemetry from the configured input source. On Windows this is the DNS Server ETW provider. On Linux this is a local dnstap UNIX domain socket. DnsStream reads the message data and hands off immediately to avoid blocking the telemetry delivery path.
Queue. The normalised message is placed into a configurable in-memory ring buffer. This decouples capture from forwarding and absorbs bursts in DNS query volume. If the forwarding target is temporarily unavailable, messages accumulate in the buffer rather than being dropped. Buffer size is configurable.
Parse. Dedicated forwarding threads drain messages from the queue. Common DNS record types are decoded into structured fields if a text based message format is configured - uncommon types are preserved as hex-encoded RDATA.
Forward. The dedicated forwarding threads serialise messages into the configured output format and transmit them over a persistent TCP connection to the configured forwarding target, optionally using TLS.
The available message types depend on the telemetry source.
Windows ETW deployments generate client query, client response, resolver query and resolver response messages.
Linux dnstap deployments generate messages derived from dnstap message types exposed by the DNS server, including client query and client response messages where supported by the upstream DNS implementation.
The Messages & output formats documention identifies all supported message types.
DnsStream serialises messages into the configured output format on the forwarding thread before transmission. The output format is set in dnsstream.conf and requires a service restart to change.
| Format | Description |
|---|---|
json |
Newline-delimited JSON (NDJSON). One JSON object per message per line. |
querylog |
DNS payload in BIND querylog style. |
dnstap |
DNS telemetry emitted as generated dnstap messages over Frame Streams (fstrm) using TCP or TLS. |
For querylog, messages are carried as a syslog message body using one of the following:
<priority>MMM DD HH:MM:SS hostname appname[pid]: <message><priority>1 ISO8601timestamp hostname appname pid - - <message>For json, messages use a two-level structure: a top-level envelope (timestamp, host, schema version, message type) and a data object carrying the DNS message fields. The schema version field (schema) is incremented on breaking changes; breaking changes are published in the DnsStream changelog.
For dnstap output, DnsStream serialises its internal DNS message model as generated dnstap messages. Messages originating from either Windows ETW or Linux dnstap inputs can be forwarded as dnstap over TCP or TLS.
Detailed output format information is provided in the Messages & output formats documention.
DnsStream can be configured to simply forward captured messages as dnstap or translate them into a different format, i.e.:
The forwarding target is configured as an IP address or DNS name. If a DNS name is used, DnsStream resolves it when it attempts to connect - DnsStream cycles through all resolved addresses until one connects successfully. This allows Core users to implement network recovery using multiple A or AAAA records and allowing DnsStream to move on to the next on failure or by manually invoking failover by modifying the address in the DNS record - since only one forwarder target is supported in Core.
All output formats use a persistent TCP connection. DnsStream maintains a single long-lived connection per configured forwarding target and reconnects automatically on failure. For json and querylog, messages are written directly to the TCP or TLS stream. For dnstap, generated dnstap messages are carried over Frame Streams (fstrm) on TCP or TLS. For both Core and Assured, all configured forwarder targets will connect, however, for Core users only the first configured forwarder target configured will process messages in the forwarding queue.
If all forwarding hosts become unreachable, DnsStream continues capturing into the ring buffer while attempting to establish a connection. Messages accumulated in the buffer during an outage are forwarded once connectivity is restored. Messages are only lost if the ring buffer fills completely before the connection is re-established, in this case older messages are overwritten. Buffer sizing guidance is in the Ring buffer behaviour section in the Network recovery documentation.
The Network recovery document details DnsStream’s connection model and recovery behaviour.
All DnsStream settings are defined in a single plain text configuration file, dnsstream.conf. On Windows the configuration file is located in %ProgramData%\Telemity\DnsStream. On Linux the configuration file is located in /opt/telemity/dnsstream/data. The file is read at startup; changes require a service restart.
A minimal working configuration to send messages to a forwarder target requires only one forwarder directive. Additional directives are required to change the message format, for example message-format dnstap to emit dnstap messages.
All configuration paramters are detailed in the Configuration reference documentation.
CPU - DnsStream’s CPU usage is approximately 25% of the CPU used by the DNS Server process at any given time. This is a stable proportional ratio, not a fixed ceiling - it scales naturally with query volume. On a server under full DNS load, both processes together leave substantial headroom on modern server hardware.
Throughput - DnsStream is designed for high-volume DNS environments. Throughput depends on the configured telemetry source, message format, forwarding protocol, and hardware platform. DnsStream can comfortably sustain an ingestion well in excess of 300,000 continuous DNS queries and responses per second.
Memory - Memory usage is fixed and determined entirely by the ring buffer configuration. At default settings (100 MB buffer) total DnsStream process memory is approximately 115 MB. This figure does not grow with query volume. On busy servers where longer forwarding outages need to be accommodated, the buffer size can be increased.
Disk I/O - There is no disk I/O in the DnsStream data path. All pipeline stages - ETW callback/dnstap ingest, ring buffer, parsing, serialisation, and TCP transmission - operate entirely in memory. The only disk writes DnsStream makes are periodic application-level entries to the local system log, written at the configured metrics interval (default: every 600 seconds). These are low-frequency, low-volume writes consistent with normal system service behaviour. Additionally, if queue recovery is active, queued messages are serialised to a disk file when DnsStream is stopped, the file is then loaded on start so that the messages are not lost during a restart.
DNS service impact - DnsStream is a passive consumer. It does not modify DNS Server configuration, does not intercept DNS responses, and introduces no execution path into the DNS service. In production deployments, DNS query latency and resolution performance are not affected. If DnsStream stops or crashes for any reason, the DNS Server service continues operating without interruption.
DnsStream has the following platform requirements:
DnsStream is distributed as platform-specific archives containing (zip on Windows, tgz on Linux):
dnsstream.exe/dnsstream.bin - the DnsStream binary (~2 MB, signed on Windows)dnsstream.conf.default - default configuration file for new installationseula.txt - end user license agreementinstall.ps1/install.sh - Platform service installation scriptuninstall.ps1/uninstall.sh - Platform service removal scriptversion.txt - DnsStream versionInstallation involves extracting the archive, running the install script with administrator/root privileges, editing the installed dnsstream.conf and starting the DnsStream platform service. The install script registers DnsStream as a system service with automatic startup. No EXE installer, no package manager, and no reboot are required. Administrators can read the installer script to see exactly what it does.
DnsStream can be run in console mode to verify the configuration and confirm messages are flowing:
# Windows
& $Env:ProgramFiles\Telemity\DnsStream\dnsstream.exe run-stdout $Env:ProgramData\Telemity\DnsStream\dnsstream.conf
# Linux
/opt/telemity/dnsstream/bin/dnsstream.bin run-stdout /opt/telemity/dnsstream/data/dnsstream.conf
Console mode prints messages to stdout in the configured format and exits cleanly on CTRL+C.
DnsStream has no interactive installer and no GUI configuration. Every aspect of installation and configuration is scriptable, making it compatible with Group Policy, Ansible, Puppet, Chef, DSC, and any tooling that can execute a PowerShell or Shell script and write a configuration file.
DnsStream is available in two editions.
DnsStream Core is free to download with no licence key and no account required. It includes:
DnsStream Assured is available on a per-instance subscription basis, and extends Core with:
Data residency. DNS messages go where dnsstream.conf directs them. No data is sent to Telemity. There are no vendor cloud services in the data path for Core or Assured deployments unless they have been configured as a forwarder target.
Binary integrity. For Windows the DnsStream binary is Authenticode-signed by Telemity Ltd. Verify the signature with Get-AuthenticodeSignature .\dnsstream.exe before installation.
Attack surface. By default DnsStream has no network listening port, no web interface and no management API. Its only network activity is outbound TCP to the configured forwarding target.
Privilege. DnsStream requires administrator/root permissions only for installation. The running service can be configured to run under a dedicated low-privilege account.
mTLS (Assured). Mutual TLS ensures that only an authorised DnsStream instance can connect to an authorised collector, and vice versa. This prevents injection of forged DNS telemetry messages and protects the telemetry stream in transit.