Get started

Administration

Administration / Configuration reference

Configuration file
Collection
1. listener etw
2. listener unix
Message queue
Message formatting
Domain enrichment
1. domain-suffix-mode
2. domain-suffix
Forwarding
1. forwarder
Metrics
1. metrics-interval
2. metrics-format
Licensing
1. license
ETW trace session

Configuration file

DnsStream is configured through a single plain-text configuration file located at %ProgramData%\Telemity\DnsStream\dnsstream.conf on Windows or /opt/telemity/dnsstream/data/dnsstream.conf on Linux. The file is read at service startup. All changes require a service restart to take effect.

The configuration file uses a key value format - one directive per line. Anything following the # character are comments and are ignored. Blank lines are ignored. Some optional directives are shipped commented out; remove the leading # to activate them. If a line is indented, and immediately follows another line, it is considered part of the proceeding line. For example, the following two configuration statements are equal:

listner etw client-query=on client-response=on

listner etw client-query=on
    client-response=on

By default not all directives are present in the configuration file. These will default to the default values defined for each directive.

Collection

`listener etw`

Available on Windows only, captures DNS telemetry directly from the Microsoft Windows DNS Server ETW provider in real-time without any data being written to disk.

listener etw [key=value ...]

This form of the listener directive can contain optional key-value parameters, all on a single line:

# Capture client-query and client-response ETW events by default
listener etw

# Switch off client-query and client-response messages and switch on resolver-query and resolver-response messages
listener etw client-query=off client-response=off resolver-query=on resolver-response=on

All key-value parameters are optional and may appear in any order after the positional arguments. Parameters not listed default to the values shown.

Name	Default	Description
`dnstap-identity`	`message-hostname`	Specifies the identity field value as dnstap messages are created from ETW events. When set to `message-hostname` uses the same value computed for the `message-hostname` property from the `dnsstream.conf` file. When set to `omit` the identity field is not included in dnstap messages.
`dnstap-version`	`omit`	Specifies the version field value as dnstap messages are created from ETW events. When set to `dnsstream` uses the string `DnsStream x.x.x` where `x.x.x` is the DnsStream version. When set to `omit` the version field is not included in dnstap messages.
`dnstap-extra`	Empty	Specifies the extra field value as dnstap messages are created from ETW events. By default the extra field is omitted.
`client-query`	on	Generate `CLIENT_QUERY` dnstap messages from ETW events.
`client-response`	on	Generate `CLIENT_RESPONSE` dnstap messages from ETW events.
`resolver-query`	off	Generate `RESOLVER_QUERY` dnstap messages from ETW events.
`resolver-response`	off	Generate `RESOLVER_RESPONSE` dnstap messages from ETW events.

`listener unix`

Available on Linux only, acts as a dnstap consumer and receives messages generated by the local DNS server from a local UNIX domain socket.

# Minimal configuration
listener unix /run/telemity/dnsstream/dnstap.sock

# Custom mode and group
listener unix /run/telemity/dnsstream/dnstap.sock mode=660 group=dnstap

This form of the listener directive takes one required positional argument followed by optional key-value parameters, all on a single line:

listener unix <path> [key=value ...]

Positional arguments

Name	Description
Path	Filesystem path of the UNIX domain socket used by the local dnstap producer. The path must not exceed the operating system UNIX socket path length limit.

All key-value parameters are optional and may appear in any order after the positional arguments. Parameters not listed default to the values shown.

Name	Default	Description
`mode`	0666	Permissions for the UNIX socket path created by DnsStream.
`group`	`dnsstream`	Name of the group assigned to the UNIX socket path created by DnsStream.
`keepalive`	`20`	Number of consecutive read timeouts permitted before the connection is considered dead and closed.
`read-timeout`	`5`	Read timeout in seconds. If no data is received during this interval, a read timeout occurs.
`write-timeout`	`5`	Write timeout in seconds. A connection is closed if data cannot be written within this interval.
`send-buffer-size`	None	Socket send buffer size in bytes. Defaults to whatever is configured for the operating system.
`recv-buffer-size`	None	Socket receive buffer size in bytes. Defaults to whatever is configured for the operating system.
`listen-backlog`	`128`	Maximum number of pending connections waiting to be accepted.
`max-connections`	`1000`	Maximum number of simultaneously active producer connections. Additional connections are rejected once this limit is reached.
`fstrm-control-frame-max-size`	`65536`	Maximum Frame Streams control frame size. If a control frame exceeds this size the connection is closed.
`fstrm-data-frame-max-size`	`262144`	Maximum Frame Streams data frame size. If a control frame exceeds this size the connection is closed.

The UNIX listener accepts standard Frame Streams (fstrm) dnstap connections and is compatible with any software capable of producing dnstap over Frame Streams, including:

BIND
Unbound
Knot DNS
PowerDNS
CoreDNS
dnsdist

All dnstap message types are accepted and forwarded when using dnstap output. When generating JSON or querylog output, only supported query and response message types are converted and forwarded. See the Messages & output formats documentation for supported messages and formats.

Message queue

`message-queue-size`

The size of the in-memory ring buffer in bytes. The buffer holds message captured that have not yet been forwarded.

message-queue-size 104857600

Default: 104857600 (approximately 100 MB) when not set.

On high-volume DNS servers or where extended forwarding outages are possible, increase this value to reduce the risk of message loss. See the Ring buffer behaviour section in the Network recovery document for buffer sizing guidance.

`message-queue-recovery`

Controls how DnsStream handles the on-disk queue file at startup, and what happens to buffered messages on a clean shutdown.

message-queue-recovery on

Value	Description
`on`	On clean shutdown, buffered messages are written to the queue file. On startup, messages are loaded from the file, then the file is deleted. Use when preserving messages across restarts is required.
`off`	In-memory messages are discarded on service stop. No queue file is written. On restart, DnsStream simply begins capturing new messages.

The queue file is only written on a clean service shutdown. Messages buffered in memory at the time of a crash, forced kill, or power failure are not recoverable regardless of this setting.

Default: on

`message-queue-filename`

The filename of the on-disk queue file. A relative path is resolved from the DnsStream data directory (%ProgramData%\Telemity\DnsStream\ on Windows and /opt/telemity/dnsstream/data on Linux). An absolute path may also be specified.

message-queue-filename message.queue

Default: message.queue

Message formatting

`message-format`

Specifies how messages are serialised before forwarding.

message-format querylog

Value	Description
`querylog`	Messages in ISC BIND querylog style over TCP or TLS. The syslog envelope is controlled by `message-syslog-format`. The message body format is controlled by `message-querylog-format`. For DNS responses a ISC BIND querylog style has been created which is similar in format to queries. See the Messages & output formats documentation for more.
`json`	Messages as structured JSON objects without a syslog envelope over TCP or TLS.
`dnstap`	Messages emitted as generated dnstap messages using Frame Streams (`fstrm`) over TCP or TLS.

When message-format dnstap is set, DnsStream forwards dnstap messages. Directives which modify textual message formatting or enrichment - such as message-querylog-format, message-fqdn-format, domain-suffix-mode, and domain-suffix - do not apply to the dnstap output.

Default: json

`message-hostname`

Overrides the hostname field written into message messages. By default DnsStream uses the local machine’s hostname as reported by Windows or Linux.

message-hostname windows2025

Value	Description
String	Any string to use in place of the local hostname. Affects the hostname field in both syslog envelopes and JSON messages, and the identity field in dnstap messages.

This directive is optional. When commented out, DnsStream uses the local machine hostname automatically. Override it when the machine hostname is not meaningful in your SIEM - for example when DNS servers are identified by a role name rather than their individual hostnames, or when running in a containerised or virtualised environment where the reported hostname is not stable.

Default: Not set (local machine hostname used).

`message-syslog-format`

These directives control the syslog envelope written around each message when message-format querylog is set.

message-syslog-format rfc5424

Value	Description
`rfc5424`	RFC 5424 structured syslog envelope. Includes a version field (`1`), an ISO 8601 UTC-aware timestamp, and nil values for message ID and structured data. Preferred for all new deployments.
`bsd`	BSD syslog (RFC 3164) envelope. Uses a `MMM DD HH:MM:SS` local-time timestamp with no year or timezone. Maximum compatibility with legacy syslog receivers.

Default: rfc5424

`message-syslog-priority`

The syslog priority value encoded in the envelope header of every outgoing syslog message when message-format querylog is set.

message-syslog-priority 30

Encoded as <N> in the syslog header. Calculated as (facility × 8) + severity. The default of 30 is facility 3 (daemon) plus severity 6 (informational). The following are example priorities:

Facility	Code	Severity	Code	Priority
daemon	3	error	3	`<27>`
daemon	3	warning	4	`<28>`
daemon	3	notice	5	`<29>`
daemon	3	informational	6	`<30>`
daemon	3	debug	7	`<31>`

Default: 30

`message-querylog-format`

Controls whether additional metadata fields are added to querylog-format messages when message-format querylog is set.

message-querylog-format extended

Value	Description
`standard`	Standard BIND querylog format. No additional fields beyond the core query and response fields. Use standard if the receiver is not able to handle the extended fields.
`extended`	Inserts size, transaction ID and domain fields into parts of the querylog message.

More information about Standard vs Extended formats can be found in message specific details under the ISC BIND querylog format section in the Messages & output formats documentation.

Default: standard

`message-fqdn-format`

Controls whether fully qualified domain names are written with a trailing dot when messages are converted into a textual representation such as querylog or JSON.

message-fqdn-format with-trailing-dot

Value	Description
`with-trailing-dot`	All FQDNs are written with a trailing dot in standard DNS presentation format - `example.com.` - with the DNS root represented as `.`. This is the default and the technically correct representation.
`without-trailing-dot`	Trailing dots are omitted - `example.com` - with the DNS root represented as an empty string. Use this if your SIEM parser or downstream tooling does not handle trailing dots correctly.

This directive affects every FQDN in every part of the message - query name, record owner names, and RDATA fields such as CNAME targets, MX exchange names, NS names, and PTR records.

Default: with-trailing-dot (trailing dot present)

Domain enrichment

These directives are used by DnsStream when identifying a DNS domain suffix for DNS query names and DNS record names - the value that appears in the qdomain and domain extended-querylog or JSON fields. For example, for both host.services.telemity.com. and www.telemity.com., the domain field will be telemity.com..

Domain enrichment helps downstream systems reason about DNS activity at the domain level instead of just individual hostnames, and adds registrable domain context to messages for easier correlation, aggregation, and downstream analysis.

`domain-suffix-mode`

Controls how DnsStream identifies the DNS domain for a query name.

domain-suffix-mode all

Value	Description
`all`	Use a built-in public suffix list combined with any `domain-suffix` directives to identify the DNS domain from any query name.
`builtin`	Use only the built-in public suffix list. Custom suffixes defined in `domain-suffix` directives are ignored.
`config`	Use only the suffixes defined in `domain-suffix` directives. The built-in list is ignored. Useful in environments where only internal domain names are expected.
`off`	Domains are not identified and domain fields will be empty or missing as specified by each message type and format.

The public suffix list is updated to the latest version with each DnsStream release.

Default: all

`domain-suffix`

Defines a custom domain suffix for DNS domain identification. Multiple directives may be present. Used when domain-suffix-mode is all or config.

domain-suffix corp.internal

Each suffix defines a boundary which the next label is treated as part of a hostname. For example, with domain-suffix corp.internal, a query for host.dept.corp.internal, dept.corp.internal or corp.internal yields a DNS domain of corp.internal.

If domain suffixes overlap the most specific one will be used.

Default: Not set.

Forwarding

`forwarder`

Defines a TCP forwarding target for messages. At least one forwarder directive is required for normal operation. Multiple forwarder directives may be present - DnsStream connects to each configured target independently. For DnsStream Core users, the first configured target will process messages from the message queue. For DnsStream Assured users, all forwarder targets process messages from the message queue.

# Used by Core and Assured
forwarder ipv4 host1.internal 514

# Second forwarder only used by Assured
forwarder ipv6 host2.internal 6514 tls=on

The directive takes three required positional arguments followed by optional key-value parameters, all on a single line:

forwarder <ipv4|ipv6> <host> <port> [key=value ...]

Positional arguments

Name	Description
Address family	`ipv4` or `ipv6`. Must match the address family of the configured host.
Host	IPv4 address, IPv6 address, or FQDN of the forwarding target. FQDNs are resolved on each connection attempt; DnsStream steps through each address until one connects successfully. For the `ipv4` address family `A` records are resolved, for the `ipv6` address family `AAAA` records are resolved.
Port	TCP port of the forwarding target.

All key-value parameters are optional and may appear in any order after the positional arguments. Parameters not listed default to the values shown with some applying to Windows or Linux only, specifically around the TLS configuration.

Name	Platform	Default	Description
`batch-size`	All platforms	`100`	The maximum number of messages to read from the message queue before sending them as a single write.
`recovery`	All platforms	`best-effort`	Controls how DnsStream handles messages that were in flight when a network connection failed. See below for a table of options.
`connect-timeout`	All platforms	`3`	Connect timeout in seconds. DnsStream abandons a connection attempt and tries the next available address after this many seconds.
`read-timeout`	All platforms	`5`	Read timeout in seconds. A connection is destroyed if data cannot be read from the network after this many seconds.
`write-timeout`	All platforms	`5`	Write timeout in seconds. A connection is destroyed if data cannot be written to the network after this many seconds.
`fstrm-mode`	All platforms	`bidirectional`	Controls the Frame Streams (`fstrm`) mode used when forwarding generated dnstap messages. Has no effect unless `message-format dnstap` is set. When set to `bidirectional` uses bidirectional fstrm negotiation. When set to `unidirectional` sends dnstap messages without bidirectional negotiation.
`fstrm-control-frame-max-size`	All platforms	`65536`	Maximum Frame Streams control frame size. If a control frame exceeds this size the connection is closed.
`tls`	All platforms	`off`	Enables TLS encryption on the forwarding connection. Set to `off` to use Plaintext TCP or `on` to use TLS-encrypted TCP. The port should be updated to match the collector’s TLS listener - commonly `6514` for syslog over TLS.
`tls-validate`	All platforms	`on`	Controls whether DnsStream validates the server’s TLS certificate. When set to `off`, certificate validation is disabled. The connection is encrypted but the server’s identity is not verified. Only appropriate for testing or where a self-signed certificate cannot be added to the trust store. When set to `on`, DnsStream verifies the server’s certificate against the trusted certificate store. Connections are rejected if the certificate is invalid, expired, or untrusted. Recommended for all production deployments.
`tls-validate-server-name`	All platforms	The `host` value from the positional arguments	The expected server name (SNI) sent during the TLS handshake and used for certificate validation. Specify this when connecting by IP address, or when the certificate subject name differs from the `host` value.
`tls-validate-ca-file`	Linux	Not set (OpenSSL default trust store)	Path to a PEM-encoded CA certificate bundle or directory of trusted CA certificates used to validate the server’s TLS certificate. When not set, the system’s default OpenSSL trust store is used. Only used when `tls-validate=on` is set.
`tls-client-certificate`	Windows	`off`	Enables mutual TLS (mTLS) by presenting a client certificate to the server during the TLS handshake. When set to `off`, no client certificate is presented, i.e. server-only TLS. When set to `auto`, DnsStream presents a client certificate which Schannel automatically selects. When set to `manual`, the certificate is located using `tls-client-certificate-store` combined with `tls-client-certificate-subject` or `tls-client-certificate-thumbprint`. The server must be configured to require and trust the client certificate.
`tls-client-certificate-store`	Windows	Not set (system default personal store)	The Windows certificate store from which the client certificate is selected. Common values are `My` (personal store), `LocalMachine` and `TrustedPeople`. The store is searched using the criteria in `tls-client-certificate-subject` or `tls-client-certificate-thumbprint`.
`tls-client-certificate-subject`	Windows	Not set (system will automatically select)	Selects the client certificate by subject name. DnsStream selects the first certificate in the configured store whose subject contains this string. Either `tls-client-certificate-subject` or `tls-client-certificate-thumbprint` can be specified when `tls-client-certificate=on` is set, if both are set `tls-client-certificate-thumbprint` is used.
`tls-client-certificate-thumbprint`	Windows	Not set (system will automatically select)	Selects the client certificate by its SHA-1 thumbprint. Exact match on the certificate’s SHA-1 thumbprint as a lowercase hex string without separators. Takes precedence over `tls-client-certificate-subject` when both are specified.
`tls-client-certificate`	Linux	`off`	Enables mutual TLS (mTLS) by presenting a client certificate to the server during the TLS handshake. When set to `off`, no client certificate is presented, i.e. server-only TLS. When set to `on`, the client certificate and private key are loaded from `tls-client-certificate-cert-file` and `tls-client-certificate-key-file`. The server must be configured to require and trust the client certificate.
`tls-client-certificate-cert-file`	Linux	Not set	Path to a PEM-encoded client certificate used for mutual TLS authentication. Required when `tls-client-certificate=on` is set.
`tls-client-certificate-key-file`	Linux	Not set	Path to the PEM-encoded private key corresponding to `tls-client-certificate-cert-file`. Required when `tls-client-certificate=on` is set.
`tls-min-version`	Linux	`1.2`	The minimum TLS protocol version permitted for outbound connections. Supported values are `1.2` and `1.3`. When not set, the OpenSSL library default is used.
`tls-max-version`	Linux	Not set (OpenSSL default)	The maximum TLS protocol version permitted for outbound connections. Supported values are `1.2` and `1.3`. When not set, the OpenSSL library default is used.
`tls-cipher-list`	Linux	Not set (OpenSSL default)	Specifies the OpenSSL cipher list for TLS 1.2 and earlier. Uses the standard OpenSSL cipher string format. When not set, the OpenSSL library default is used. Has no effect on TLS 1.3 cipher suites.
`tls-cipher-suites`	Linux	Not set (OpenSSL default)	Specifies the permitted TLS 1.3 cipher suites using the OpenSSL cipher suite string format. When not set, the OpenSSL library default is used. Has no effect on TLS 1.2 and earlier.

For the recovery option, the following are available:

Value	Description
`drop`	The batch of messages that were being sent at the time of a connection failure are discarded. DnsStream reconnects and resumes from new messages only.
`best-effort`	On reconnection, DnsStream resends the batch of messages that were in flight at the time of failure. Does not account for messages that may have appeared delivered but were not acknowledged before the connection dropped.
`durable`	On reconnection, DnsStream resends both the previous batch of messages and the batch of messages sent immediately before the failure. This guards against the case where a network error is not detected until the next send attempt, meaning some apparently-sent messages may not have been received. Recommended where message completeness is a priority.

Metrics

`metrics-interval`

How often DnsStream emits an operational metrics summary, in seconds, to the Event Log on Windows and the system log on Linux.

dnsstream-metrics-interval 600

Default: 600 (10 minutes)

`metrics-format`

Specifies how metrics are formatted.

metrics-format kv

Value	Description
`kv`	Metrics are formatted as space seperated `key=value` items enclosed brackets for groups of related metrics.
`json`	Metrics are formatted as a one-line JSON string.

See the Metrics & health documentation for more.

Default: kv

Licensing

`license`

Path to the DnsStream Assured licence file. A relative path is resolved from the DnsStream data directory (%ProgramData%\Telemity\DnsStream\ for Windows and /opt/telemity/dnsstream/data for Linux). An absolute path may also be specified.

license license.txt

DnsStream Core operates fully without a licence file. To activate Assured features, obtain a licence file from Telemity, place it in the DnsStream data directory, and restart the service.

Default: license.txt

ETW trace session

These directives control the low-level ETW session parameters used to receive ETW events from the Windows DNS Server service. In almost all deployments the defaults are correct and these do not need to be changed. They are documented here for completeness. None of the trace directives are present in the default configuration.

Directive	Default	Description
`etw-buffer-size`	`256`	Size of each ETW buffer in kilobytes.
`etw-minimum-buffers`	`0`	Minimum number of ETW buffers to allocate. `0` lets Windows decide.
`etw-maximum-buffers`	`0`	Maximum number of ETW buffers to allocate. `0` lets Windows decide.
`etw-flush-timer`	`1`	How often ETW flushes buffers to the consumer, in seconds.
`etw-filter`	`off`	Whether to apply keyword filtering at the ETW session level for specific events.
`etw-level`	`4`	ETW trace level as an integer. `4` = informational. Captures all normal events.
`etw-match-any-keyword`	`7`	ETW keyword mask as an integer. `7` captures client queries and responses.
`etw-match-all-keyword`	`0`	ETW all-keyword mask as an integer. `0` applies no additional keyword filter.

These values correspond directly to Windows ETW session configuration parameters. Changing them without a clear understanding of the ETW session model may result in events being silently missed. Contact Telemity support before modifying these directives.

If any of the directives are changed, DnsStream and its ETW trace session must be restarted as follows:

# Stop DnsStream so it is no longer consuming events from the ETW session
Stop-Service "Telemity DnsStream"

# Stop the ETW trace session
logman -ets stop "Telemity DnsStream"

# Start DnsStream again which in turn recreates the ETW trace session
Start-Service "Telemity DnsStream"

This page