1. Overview
2. Getting help
3. Before you begin
   1. Package contents
   2. Requirements
   3. Service permissions
   4. Upgrades
   5. Installation overview
4. Installation steps

Overview

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.

Getting help

The Contact page identifies how to access help with any DnsStream related queries.

Before you begin

Package contents

The distribution archive dnsstream-2.2.1-windows-x64.zip contains the following files:

Requirements

• Windows Server 2012 R2 (with KB2956577) onwards
• The Windows DNS Server role installed and running
• PowerShell running as Administrator
• Outbound TCP connectivity from the DNS server to the forwarding target
  • Installation can be verified using console mode if connectivity is not yet available

Windows Server 2012 R2

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 events.

Service permissions

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:

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:

• Administrator rights - if configured to run as a low-privileged service account
• Access to the DNS Server service configuration
• Write access to the DNS Server installation directory
• Any privilege beyond those listed above

The installation steps below includes an optional step to adjust the service account for the DnsStream Windows service.

Upgrades

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.

Installation overview

The installer creates the following directory structure if it does not already exist:

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:

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:

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.

Installation steps

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.2.1/dnsstream-2.2.1-windows-x64.zip -OutFile dnsstream-2.2.1-windows-x64.zip

# Extract
Expand-Archive -Path dnsstream-2.2.1-windows-x64.zip -DestinationPath .

# Change into the extracted directory
cd dnsstream-2.2.1-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 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 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.