DnsStream is distributed as a ZIP archive. Installation involves extracting the archive, running the included install.ps1 script with Administrator privileges, reviewing and editing the configuration file, and starting the DnsStream Windows service. No reboot is required. The Windows DNS Server service is not affected at any point during installation.
Installing DnsStream has no effect on the Windows DNS Server service. DNS resolution continues normally throughout and after the install process.
The Contact page identifies how to access help with any DnsStream related queries.
The distribution archive dnsstream-1.0.0-windows-x64.zip contains the following files:
| File | Description |
|---|---|
bin\dnsstream.exe |
The signed DnsStream binary. |
data\dnsstream.conf.default |
The default configuration file. Copied to the data directory during installation. |
eula.txt |
End user licence agreement. Review before installation. |
install.ps1 |
Installation script. Creates directories, copies files, registers the Windows Event Log source, and creates the Windows service. |
uninstall.ps1 |
Removal script. Stops and deletes the service and removes installed files. |
version.txt |
Contains the DnsStream version |
By default, the DnsStream installer creates the Windows service without specifying a service account, which causes Windows to run the service as LocalSystem. LocalSystem is a highly privileged built-in account with broad access to the local machine. For production deployments, running DnsStream under a dedicated low-privilege service account reduces the attack surface and follows the principle of least privilege.
DnsStream needs the following to operate correctly:
| Requirement | Why |
|---|---|
| Read access to the installation directory | To execute dnsstream.exe from %ProgramFiles%\Telemity\DnsStream\. |
| Read and write access to the data directory | To read dnsstream.conf and the licence file (Assured) from %ProgramData%\Telemity\DnsStream\, and write the queue file if queue-recovery is enabled in the same directory. |
| Permission to create and read an ETW trace session | To subscribe to the Microsoft-Windows-DNSServer ETW provider and receive DNS events. Requires membership of the Performance Log Users built-in group, or Administrator rights. |
| Permission to write to the Windows Event Log | To write operational metrics and status entries under the Telemity DnsStream event source. Access to the Event Log Readers built-in group can be granted, or WriteKey registry access rule set to Allow for the path HKLM:\SYSTEM\CurrentControlSet\Services\EventLog\Telemity DnsStream |
| Log on as a service | Required for any account used as a Windows service identity. |
| Outbound TCP network access | To connect to the configured forwarding target. This is a network-level permission, not a Windows privilege, but firewall rules should be scoped to the service account where your firewall supports identity-based rules. |
Note that the paths %ProgramFiles%\Telemity\DnsStream\, %ProgramData%\Telemity\DnsStream\ and the Windows Event Log Telemity DnsStream can be created ahead of installation if a low-privileged user needs to be prepared, e.g.:
New-Item -ItemType Directory -Path "$Env:ProgramFiles\Telemity\DnsStream"
New-Item -ItemType Directory -Path "$Env:ProgramData\Telemity\DnsStream"
New-EventLog "Telemity DnsStream" "Telemity DnsStream"
Once installed, DnsStream does not require:
The installation steps below includes an optional step to adjust the service account for the DnsStream Windows service.
The installer script is upgrade aware. If it detects an existing installation it will not overwrite the existing configuration. DnsStream aims to be fully backwards compatible with any configuration or data files used in previous versions.
Windows ETW buffers events in kernel memory independently of any consumer process. When DnsStream is stopped during an upgrade, the ETW session continues running and accumulates events in its kernel-side buffers. DnsStream does not need to be running for events from the DNS Server service to continue to be buffered.
When DnsStream restarts after the upgrade and re-attaches to the Microsoft-Windows-DNSServer ETW provider, it receives the buffered events that accumulated during the downtime before receiving new ones. Provided the upgrade completes within the ETW buffer window, no events are lost. Since upgrades are typically completed within a few minutes, this is only a concern for very busy environments.
The installer creates the following directory structure if it does not already exist:
| Path | Purpose |
|---|---|
%ProgramFiles%\Telemity\DnsStream\ |
Binary files. Contains dnsstream.exe and uninstall.ps1. |
%ProgramData%\Telemity\DnsStream\ |
Configuration and runtime data. Contains dnsstream.conf, dnsstream.conf.default, the queue file if persistence is enabled, and the Assured license file installed. |
The separation of binary files and data files follows Windows conventions and allows the binary directory to be locked down to read-only access for non-administrator accounts while the data directory remains writable by the service.
The installer copies the following files:
| File | Path |
|---|---|
| Binary | %ProgramFiles%\Telemity\DnsStream\dnsstream.exe |
| PowerShell uninstaller | %ProgramFiles%\Telemity\DnsStream\uninstall.ps1 |
| Configuration | %ProgramData%\Telemity\DnsStream\dnsstream.conf |
| Default configuration | %ProgramData%\Telemity\DnsStream\dnsstream.conf.default |
If a service named Telemity DnsStream already exists when the installer runs - for example during an upgrade - the installer stops it if running before proceeding.
The installer registers Telemity DnsStream as a Windows Event Log source if it is not already present. This is required for DnsStream to write operational metrics and status entries to the Windows Event Log.
The installer creates a Windows service with the following properties if it doesn’t already exist:
| Property | Value |
|---|---|
| Service name | Telemity DnsStream |
| Display name | Telemity DnsStream |
| Binary path | "%ProgramFiles%\Telemity\DnsStream\dnsstream.exe" "run-service" "%ProgramData%\Telemity\DnsStream\dnsstream.conf" |
| Startup type | Automatic |
The service is created but not started by the installer. This is intentional - it gives you the opportunity to review and adjust the configuration before the service begins forwarding events (i.e. the account the service will start with can be changed). Start the service once you are satisfied with the configuration.
Download, extract and install
By downloading or using DnsStream you are accepting the DnsStream end user license
Using a PowerShell window with Administrator privileges, download the DnsStream ZIP from the Telemity website, extract it to your preferred directory on the Windows DNS server, then review and run the install.ps1 installer script as an Administrator (Expand-Archive is not available on Windows 2012 R2, in this case the archive must be expanded using file explorer or some other tool).
# Download
iwr https://telemity.com/downloads/dnsstream/1.0.0/dnsstream-1.0.0-windows-x64.zip -OutFile dnsstream-1.0.0-windows-x64.zip
# Extract
Expand-Archive -Path dnsstream-1.0.0-windows-x64.zip -DestinationPath .
# Change into the extracted directory
cd dnsstream-1.0.0-windows-x64
# Run the installer - this is upgrade aware and retains existing configuration
.\install.ps1
Configure
For first time installations, after running the installer, edit %ProgramData%\Telemity\DnsStream\dnsstream.conf to set the forwarding target using the forwarder directive. See the Configuration reference for full documentation of all available directives. If a configuration file has been prepared ahead of installation, or is managed using automation tools, at this point an organizations dnsstream.conf can be copied over the top of the %ProgramData%\Telemity\DnsStream\dnsstream.conf file.
Optionally set service account
For first time installations, before starting the DnsStream Windows service, optionally configure its service account (see Service permissions for required permissions):
# Local account
sc.exe config "Telemity DnsStream" obj= ".\AccountUsername" password= "AccountPassword"
# gMSA
sc.exe config "Telemity DnsStream" obj= "DOMAIN\AccountUsername$" password= ""
Start
Finally, start the DnsStream Windows service and then confirm DNS events are reaching your collector.
Start-Service -Name "Telemity DnsStream"
If you want to observe events directly before committing to service mode, or if the configured forwarder target is not available, stop the service if running and run DnsStream in console mode. DnsStream prints events to the console windows as per the format configured in the dnsstream.conf file.
Stop-Service -Name "Telemity DnsStream"
& "$Env:ProgramFiles\Telemity\DnsStream\dnsstream.exe" run-stdout "$Env:ProgramData\Telemity\DnsStream\dnsstream.conf"
Press CTRL+C to stop. Once satisfied, start the service again.