Created a PowerShell Module for Serverless-dns for Windows 11

[HotCakeX]

Hello, I created a PowerShell Module for Serverless-dns for Windows 11

I personally use it and battle tested it to make sure it works in almost any condition. you could pin this or something so Windows users visiting this repository will be able to find it and use self-hosted serverless-dns easily and handle the dynamic IP address situation (which is fundamentally a good thing), but it's up to you, please let me know what you think.

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. Operation modes
2. About The Module
3. Features
4. Recommended setup
5. Prerequisites
6. Installation
7. Usage
   • Built-in DoH examples
   • Custom DoH examples
   • Dynamic DoH examples

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)

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.

All of the connections to Cloudflare and Google servers use direct IP, are set to use TLS 1.3 with TLS_CHACHA20_POLY1305_SHA256 cipher suite and use HTTP/2

💡(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 is not supported

• 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/ -AutoDetectDoHIPs

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

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)

Upcoming features

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

[ignoramous]

This looks great! Thanks 👍

I'll add it to the project's readme in the coming day or so.

---

If I may, why query every 5mins? Sounds a bit drastic? Once every 2h sounds okay too; or, perhaps, this time period be configurable?

[HotCakeX]

Thank you, glad to hear that :)

Version 0.0.7 addresses issues mentioned below.

my idea was to minimize the chance of system DNS server IP addresses being unreachable as much as possible, that's why I set it to check every 5 minutes for new IPs, like for example if the check just has been done and after few seconds, all 4 IP addresses of the server (2 IPv4 and 2 IPv6) changed then system would be unable to resolve any domain names for the next ~4 minutes. that said, I've been keeping an eye on my own Cloudflare hosted serverless-dns and its IPv4s haven't changed in a few days. beyond that observation, I don't have any more info about how often the IPs change.

I also assume (not 100% sure) that querying 1 domain name every x minutes shouldn't affect the ping or Internet connection of users. definitely need feedback on that too.

I'm sure you have more information about that, could you tell me that whenever Cloudflare hosted DoH server's IP addresses change, are both IPv4 addresses changed at the same time or only one of them is? how about IPv6s? these info could help choose a proper default interval for the module.

of course, after the task is created, you can go to task scheduler and change the interval using GUI.

I can create an optional 3rd parameter for the module so users can choose a different interval.

p.s also possible to make the first trigger run every 2 hours, create another trigger which causes the module to run ~5 seconds after internet connectivity failure detected, then do this maybe 2 more times with 1-minute intervals (in case the connectivity isn't returned and failure was due to loss of WIFI/VPN/network connection), Windows has an event dedicated for it. all of it can be fine-tuned using task scheduler GUI too.

[HotCakeX]

@ignoramous
I just released version 0.0.7

• modified the scheduled task trigger to run every 2 hours and added a 2nd trigger so the module will run the moment system detects DNS failure

tested it and works well, the specific event is only triggered due to DNS failure and Not when network is changed, Internet is manually turned off by user, VPN is connected/disconnected etc.

full updated description for that change:

• Once you run this module for the first time and supply it with your DoH template and DoH domain, it will create a scheduled task that will run the module automatically based on 2 distinct criteria; 1) as soon as Windows detects the current DNS servers are unreachable 2) every 2 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 miliseconds after Windows detects DNS servers are unreachable, and even then, Windows still maintains the current active connections using the DNS cache.

if there is any other modification needed please let me know.

Currently things in my to-do:

• Support dynamic IP DoT server - ask users if they want to use DoT or DoH and change things accordingly
• see if it's possible to perform DNS query when system DNS isn't available, using Cloudflare's API for encrypted DNS instead of plain-text.