README.md

WinSecureDNSMgr module

Quick, proper and automatic way to configure Secure DNS in Windows with multiple available operation modes

PowerShell Gallery

Discussion · Report Issue

Table of Contents

1. About The Module
2. Features
3. Recommended setup
4. Prerequisites
5. Installation
6. Usage
   • Built-in DoH examples
   • Custom DoH examples
   • Dynamic DoH examples
7. Operation modes

About The Module

This is a PowerShell module that can simplify setting up DNS over HTTPS in Windows for various scenarios mentioned in the Operation modes section.

It can automatically identify the correct and active network adapter/interface and set Secure DNS settings for it based on parameters supplied by user. That means it will detect the correct network adapter/interface even if you are using:

• Windows built-in VPN connections (PPTP, L2TP, SSTP, IKEv2)
• OpenVPN
• TUN/TAP virtual adapters (a lot of programs use them, including WireGuard)
• Hyper-V virtual switches (Internal, Private, External, all at the same time)
• Cloudflare WARP client

💡(back to top)

Features

Strongest possible End-to-End encrypted workflow

Created, targeted and tested on the latest version of Windows, on physical hardware and Virtual Machines

To make sure the module will always be able to acquire the IP address(s) of the DoH server, specially in case of dynamic DoH server when the currently set system IPv4s and IPv6s might be outdated, the module performs DNS queries in this exact order:

First tries using Cloudflare's main encrypted API to get the IP address(s) of the DoH server's domain.

If 1st one fails, tries using the Cloudflare's secondary encrypted API to get the IP address(s) of the DoH server's domain.

If 2nd one fails, tries using Google's main encrypted API to get the IP address(s) of the DoH server's domain.

If 3rd one fails, tries using Google's secondary encrypted API to get the IP address(s) of the DoH server's domain.

if 4th one fails, tries using any system DNS that is available to get the IP address(s) of the DoH server's domain.

All of the connections to Cloudflare and Google servers use direct IP, are set to use TLS 1.3 with HTTP/3, with the exception of the last try which uses system DNS as the last resort before giving up.

💡(back to top)

Recommended setup

• Use Cloudflare DNS over HTTPS which is a built-in DoH provider in Windows, it's the safest, fastest and most reliable.

• If you can't use publicly known DNS over HTTPS providers for any reason, you can create your own DoH server and domain for free using a serverless Secure DNS and freenom. They are more stealthy, hard or costly for ISPs, governments etc. to detect or block.

💡(back to top)

Prerequisites

• The latest stable version of PowerShell

  • Install it from GitHub
  • Using Winget Winget install Microsoft.PowerShell
  • Store installed version of PowerShell is not supported for the Dynamic DoH (DDOH) operation mode.

• Latest version of Windows

If planning to use the module in dynamic DoH mode and it's the first time installing PowerShell on your machine, restart your computer after installation so task scheduler will recognize pwsh.exe required for running this module.

💡(back to top)

Installation

Install from PowerShell Gallery

Install-Module -Name WinSecureDNSMgr -force

if you already have the module installed, make sure it's up-to-date

Update-Module -Name WinSecureDNSMgr -force

💡(back to top)

Usage

Built-in DoH examples

Set-BuiltInWinSecureDNS -DoHProvider Cloudflare

Set-DOH -DoHProvider Cloudflare

Custom DoH examples

Set-CustomWinSecureDNS -DoHTemplate https://example.com/

Set-CDOH -DoHTemplate https://example.com/

Set-CDOH -DoHTemplate https://example.com -IPV4s 1.2.3.4 -IPV6s 2001:db8::8a2e:370:7334

Dynamic DoH examples

Set-DynamicIPDoHServer -DoHTemplate https://example.com/

Set-DDOH -DoHTemplate https://example.com/

💡(back to top)

Operation modes

DNS over HTTPS in Windows using the default built-in OS DoH providers

• This is the default mode of operation for this module. It will set up DNS over HTTPS in Windows using the default built-in OS DoH providers, which are Cloudflare, Quad9 and Google.

• In this mode of operation, the active network adapter/interface will be detected automatically but you will have the option to review it and choose a different one if you like.

DNS over HTTPS in Windows using a custom DoH provider that has static IP address(s)

• This mode of operation is useful when you want to use a custom DoH provider that has static IP address(s). You can supply the module with a DoH template and then you have 2 options

  • Let the module automatically detect the IP address(s) of the DoH server and set them in Windows
  • Supply the module with the IP address(s) of the DoH server and let it set them in Windows

• In this mode of operation, the active network adapter/interface will be detected automatically but you will have the option to review it and choose a different one if you like.

DNS over HTTPS in Windows using a custom DoH provider that has dynamic IP address(s)

• This mode of operation is useful when you want to use a custom DoH provider that has dynamic IP address(s).

• Once you run the module in this mode for the first time and supply it with your DoH template, it will create a scheduled task that will run the module automatically based on 2 distinct criteria:

  • As soon as Windows detects the current DNS servers are unreachable

  • Every 6 hours in order to check for new IP changes for the dynamic DoH server

    • You can fine-tune the interval in Task Scheduler GUI if you like. I haven't had any downtimes in my tests because the module runs milliseconds after Windows detects DNS servers are unreachable, and even then, Windows still maintains the current active connections using the DNS cache. if your experience is different, please let me know on GitHub.

• The module and the scheduled task will use both IPv4s and IPv6s of the dynamic DoH server. The task will run whether or not any user is logged on.

• In this mode of operation, the active network adapter/interface will be detected automatically.

💡(back to top)

Upcoming features

• DNS over TLS (DoT) support
  • It's currently only available in Windows insider builds, Dev and Canary channels.