DnsStream is available for both Windows and Linux. On Windows, DnsStream collects DNS telemetry directly from the Microsoft DNS Server ETW provider. On Linux, DnsStream receives native dnstap telemetry from local DNS servers over a UNIX domain socket.
Installation consists of installing the platform package, reviewing the configuration file, and starting the DnsStream service.
Installing DnsStream has no effect on the Windows or Linux DNS Server service. DNS resolution continues normally throughout and after the install process. No reboot is required.
For Linux, the DNS server may require additional dnstap configuration, however this is not required for installation and may be done after.
The Contact page identifies how to access help with any DnsStream related queries.
The distribution archive dnsstream-2.4.4-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 |
Windows Server 2012 R2 requires Microsoft update KB2956577 to enable DNS analytic ETW events. Without this update, the Microsoft-Windows-DNSServer ETW analytic channel used by DnsStream will not produce DNS telemetry.
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 messages-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 messagess. 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 and dnsstream.conf.default. |
The separation of binary 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 - and it is running, it issues a stop command 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 messages (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 (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/2.4.4/dnsstream-2.4.4-windows-x64.zip -OutFile dnsstream-2.4.4-windows-x64.zip
# Extract
Expand-Archive -Path dnsstream-2.4.4-windows-x64.zip -DestinationPath .
# Change into the extracted directory
cd dnsstream-2.4.4-windows-x64
# Check signed files have a status of "Valid":
(Get-AuthenticodeSignature bin\dnsstream.exe).Status
(Get-AuthenticodeSignature install.ps1).Status
# Check signed files have a subject of "CN=Telemity Ltd, O=Telemity Ltd, L=Redhill, S=Surrey, C=GB":
(Get-AuthenticodeSignature bin\dnsstream.exe).SignerCertificate.Subject
(Get-AuthenticodeSignature install.ps1).SignerCertificate.Subject
# 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.
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 messages are reaching your collector.
Start-Service -Name "Telemity DnsStream"
If you want to observe messages 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 messages to the console window 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.
When running in console mode, DnsStream does not load the forwarding queue from disk at startup or persist it to disk during shutdown. This avoids permission and ownership issues that can occur when the DnsStream service is configured to run under a low-privileged service account.
The distribution archive dnsstream-2.4.4-linux-x64.tgz contains the following files:
| File | Description |
|---|---|
bin/dnsstream.bin |
The DnsStream binary. |
data/dnsstream.conf.default |
Default configuration file. |
install.sh |
Linux installation script. |
uninstall.sh |
Linux removal script. |
eula.txt |
End user licence agreement. |
version.txt |
Contains the DnsStream version. |
openssl version or openssl3 version to check for installed version)The Linux installer configures DnsStream to run as the dnsstream user and group. This user must be created ahead of or during installation. The dnsstream user is assigned the following during installation:
/opt/telemity and all files and folders underneath/run/telemity and all files and folders underneathtelemity-dnsstream serviceDnsStream does not require root privileges after installation.
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.
Unlike ETW for Windows, dnstap producers typically maintain a live connection to DnsStream. During an upgrade this connection is interrupted and the DNS server reconnects when DnsStream starts again.
Any telemetry generated while DnsStream is unavailable may be lost depending on the buffering behaviour of the dnstap producer.
The installer creates the following directory structure if it does not already exist:
| Path | Purpose |
|---|---|
/opt/telemity/dnsstream/bin |
Binary files. Contains dnsstream.exe and uninstall.ps1. |
/opt/telemity/dnsstream/data |
Configuration and runtime data. Contains dnsstream.conf and dnsstream.conf.default. |
/run/telemity/dnsstream/ |
Contains dnstap.sock for local dnstap producers to connect to. |
The installer copies the following files:
| File | Path |
|---|---|
| Binary | /opt/telemity/dnsstream/bin/dnsstream.bin |
| Bash uninstaller | /opt/telemity/dnsstream/bin/uninstall.sh |
| Configuration | /opt/telemity/dnsstream/data/dnsstream.conf |
| Default configuration | /opt/telemity/dnsstream/data/dnsstream.conf.default |
If a service named telemity-dnsstream already exists when the installer runs - for example during an upgrade - and it is running, it issues a stop command before proceeding.
The installer creates the system service with the following properties:
| Property | Value |
|---|---|
| Name | telemity-dnsstream |
| Path | /etc/systemd/system/telemity-dnsstream.service |
| Description | Telemity DnsStream |
| Type | Simple |
| Command | /opt/telemity/dnsstream/bin/dnsstream.bin run /opt/telemity/dnsstream/data/dnsstream.conf |
| Run as user | dnsstream |
| Run as group | dnsstream |
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 messages. 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 bash shell with root privileges, download the DnsStream tgz from the Telemity website, extract it to your preferred directory on the Linux DNS server, create the dnsstream user if it does not already exist, then review and run the install.sh installer script.
# Download
curl -LO https://telemity.com/downloads/dnsstream/2.4.4/dnsstream-2.4.4-linux-x64.tgz
# Extract
tar -xzf dnsstream-2.4.4-linux-x64.tgz
# Change into extracted directory
cd dnsstream-2.4.4-linux-x64
# Create the dnsstream user and group if they do not already exist
groupadd --system dnsstream
useradd --system --no-create-home --gid dnsstream --shell /usr/sbin/nologin dnsstream
# Run installer
./install.sh
Configure
For first time installations, after running the installer, edit /opt/telemity/dnsstream/data/dnsstream.conf to set the forwarding target using the forwarder directive. See the Configuration reference for full documentation of all available directives.
Start
Finally, start the DnsStream service and then confirm DNS messages are reaching your collector.
systemctl start telemity-dnsstream
If you want to observe message 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 messages to the console window as per the format configured in the dnsstream.conf file.
systemctl stop telemity-dnsstream
/opt/telemity/dnsstream/bin/dnsstream.bin run-stdout /opt/telemity/dnsstream/data/dnsstream.conf
Press CTRL+C to stop. Once satisfied, start the service again.
When running in console mode, DnsStream does not load the forwarding queue from disk at startup or persist it to disk during shutdown. This avoids permission and ownership issues that can occur when the DnsStream service is configured to run under a low-privileged service account.