DnsStream is configured through a single plain-text configuration file located at %ProgramData%\Telemity\DnsStream\dnsstream.conf. 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. Lines beginning with # are comments and are ignored. Blank lines are ignored. Some optional directives are shipped commented out; remove the leading # to activate them.
Note that not all directives may be present in the configuration file. These will default to the values defined for each directive.
log-eventSpecifies which DNS event types DnsStream captures and forwards. Each type is enabled with a separate log-event directive. Multiple directives may be present. If no log-event directives are present, no events are captured.
log-event client-query
log-event client-response
log-event parse-error
log-event metrics
The following options are available:
| Value | Description |
|---|---|
client-query |
An inbound DNS query received by the DNS Server service. |
client-response |
A DNS response sent by the DNS Server service. |
parse-error |
A DNS packet received by DnsStream in an ETW event record that could not be parsed. |
metrics |
Metrics periodically logged for the ETW trace session, network clients and the event forwarding queue. |
Default: If no log-event directives are present then no events are enabled.
This metrics event is independant of the log-metrics-to-eventlog directive. Metrics can be logged to both network and Windows Event Log, one of these or none of these.
log-formatSpecifies how DNS events are serialised before forwarding.
log-format querylog
| Value | Description |
|---|---|
querylog |
DNS events in ISC BIND querylog style. The syslog envelope is controlled by log-syslog-format. The message body format is controlled by log-querylog-format. For DNS responses a ISC BIND querylog style has been created which is similar in format to queries. See the Events & output formats documentation for more. |
json |
DNS events as structured JSON objects without a syslog envelope. |
Default: querylog
log-hostnameOverrides the hostname field written into event messages. By default DnsStream uses the local machine’s hostname as reported by Windows.
log-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 events. |
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).
log-syslog-formatThese directives control the syslog envelope written around each event when log-format querylog is set.
log-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
log-syslog-priorityThe syslog priority value encoded in the envelope header of every outgoing syslog message when log-format querylog is set.
log-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
log-querylog-formatControls whether additional metadata fields are added to querylog-format messages. Has no effect when log-format json is set - the fields are always present for JSON formatted events.
log-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 a size, transaction and domain field into parts of the querylog message. |
Moer inforamtion about Standard vs Extended formats can be found in event specific details under the ISC BIND querylog format section in the Events & outout formats documentation.
Default: standard
log-trailing-dotControls whether fully qualified domain names are written with a trailing dot.
log-trailing-dot on
| Value | Description |
|---|---|
on |
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. |
off |
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 event - query name, record owner names, and RDATA fields such as CNAME targets, MX exchange names, NS names, and PTR records.
Default: on (trailing dot present)
log-metrics-to-eventlogControls whether DnsStream periodically writes events to the Windows Event Log.
log-metrics-to-eventlog on
| Value | Description |
|---|---|
on |
Write metrics entries to the Windows Event Log under the Telemity DnsStream provider. |
off |
Don’t write metrics to the Windows Event Log. May make sense for some users who only want metrics forwarded using the log-event metrics directive which is independant of this directive. |
See Metrics & health for metrics event structure and field reference.
Default: on
log-metrics-intervalHow often DnsStream emits an operational metrics summary, in seconds.
log-metrics-interval 600
Default: 600 (10 minutes)
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 DNS events for easier correlation, aggregation, and downstream analysis.
domain-suffix-modeControls 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 event type and format. |
Default: all
domain-suffixDefines 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.
queue-sizeThe size of the in-memory ring buffer in bytes. The buffer holds events captured from ETW that have not yet been forwarded.
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 event loss. See the Network recovery for buffer sizing guidance.
queue-recoveryControls how DnsStream handles the on-disk queue file at startup, and what happens to buffered events on a clean shutdown.
queue-recovery on
| Value | Description |
|---|---|
on |
On clean shutdown, buffered events are written to the queue file. On startup, events are loaded from the file, then the file is deleted. Use when preserving events across restarts is required. |
off |
In-memory events are discarded on service stop. No queue file is written. On restart, DnsStream begins capturing from the current point in the ETW stream. |
The queue file is only written on a clean service shutdown. Events buffered in memory at the time of a crash, forced kill, or power failure are not recoverable regardless of this setting.
Default: on
queue-filenameThe filename of the on-disk queue file. A relative path is resolved from the DnsStream data directory (%ProgramData%\Telemity\DnsStream\). An absolute path may also be specified.
queue-filename dnsstream.queue
Default: dnsstream.queue
forwarderDefines a TCP forwarding target for events. 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 which does not have client certificate TLS options on will process events from the forwarding queue. For DnsStream Assured users, all forwarder targets process events from the forwarding queue.
forwarder ipv4 host1.internal 514
forwarder ipv6 host2.internal 6514 tls=on tls-client-certificate=outo
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.
| Name | Default | Description |
|---|---|---|
connect-timeout |
3 |
Connect timeout in seconds. DnsStream abandons a connection attempt and tries the next available address after this many seconds. |
read-timeout |
5 |
Read timeout in seconds. A connection is destroyed if data cannot be read from the network after this many seconds. |
write-timeout |
5 |
Write timeout in seconds. A connection is destroyed if data cannot be written to the network after this many seconds. |
tls |
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 |
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-server-name |
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-client-certificate |
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 |
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 |
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 |
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. |
forwarder-batch-sizeThe maximum number of events to read from the forwarding queue before sending them as a single TCP write.
forwarder-batch-size 10
| Value | Description |
|---|---|
| Integer | DnsStream accumulates up to this many events and writes them in a single call. Higher values reduce the number of TCP writes. |
Default: 10
forwarder-recoveryControls how DnsStream handles events that were in flight when a network connection failed.
forwarder-recovery durable
| Value | Description |
|---|---|
drop |
The batch of events that were being sent at the time of a connection failure are discarded. DnsStream reconnects and resumes from new events only. |
best-effort |
On reconnection, DnsStream resends the batch of events that were in flight at the time of failure. Does not account for events that may have appeared delivered but were not acknowledged before the connection dropped. |
durable |
On reconnection, DnsStream resends both the previous batch of events and the batch of events 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 events may not have been received. Recommended where event completeness is a priority. |
Default: durable
licensePath to the DnsStream Assured licence file. A relative path is resolved from the DnsStream data directory (%ProgramData%\Telemity\DnsStream\). An absolute path may also be specified.
license license.txt
| Value | Description |
|---|---|
| Path string | Relative or absolute path to the licence file. If present and valid, DnsStream Assured features become available - e.g. multiple forwarder targets and mTLS support. |
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
These directives control the low-level ETW session parameters used to receive DNS 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 |
|---|---|---|
trace-buffer-size |
256 |
Size of each ETW buffer in kilobytes. |
trace-minimum-buffers |
0 |
Minimum number of ETW buffers to allocate. 0 lets Windows decide. |
trace-maximum-buffers |
0 |
Maximum number of ETW buffers to allocate. 0 lets Windows decide. |
trace-flush-timer |
1 |
How often ETW flushes buffers to the consumer, in seconds. |
trace-filter |
off |
Whether to apply keyword filtering at the ETW session level. off captures all DNS Server events. |
trace-level |
4 |
ETW trace level as an integer. 4 = informational. Captures all normal DNS events. |
trace-match-any-keyword |
7 |
ETW keyword mask as an integer. 7 captures client queries and responses. |
trace-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"