Release ctrld-client

.github/workflows/ci.yml

@@ -9,18 +9,18 @@ jobs:
       fail-fast: false
       matrix:
         os: ["windows-latest", "ubuntu-latest", "macOS-latest"]
-        go: ["1.24.x"]
+        go: ["1.26.x"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 1
-      - uses: WillAbides/setup-go-faster@v1.8.0
+      - uses: actions/setup-go@v6
         with:
           go-version: ${{ matrix.go }}
       - run: "go test -race ./..."
-      - uses: dominikh/staticcheck-action@v1.3.1
+      - uses: dominikh/staticcheck-action@v1.4.0
         with:
-          version: "2025.1"
+          version: "2025.1.1"
           install-go: false
           cache-key: ${{ matrix.go }}

.gitignore

@@ -12,3 +12,10 @@ ctrld-*
 
 # generated file
 cmd/cli/rsrc_*.syso
+ctrld
+ctrld.exe
+
+# Local planning artifacts - never commit
+/SPEC.md
+/tasks/
+/SPEC-*.md

README.md

@@ -11,7 +11,6 @@ A highly configurable DNS forwarding proxy with support for:
 - Multiple upstreams with fallbacks
 - Multiple network policy driven DNS query steering (via network cidr, MAC address or FQDN)
 - Policy driven domain based "split horizon" DNS with wildcard support
-- Integrations with common router vendors and firmware
 - LAN client discovery via DHCP, mDNS, ARP, NDP, hosts file parsing
 - Prometheus metrics exporter 
 
@@ -25,50 +24,32 @@ All DNS protocols are supported, including:
 - `DNS-over-HTTP/3` (DOH3)
 - `DNS-over-QUIC`
 
-# Use Cases
-1. Use secure DNS protocols on networks and devices that don't natively support them (legacy routers, legacy OSes, TVs, smart toasters).
+## Use Cases
+1. Use secure DNS protocols on networks and devices that don't natively support them (legacy OSes, TVs, smart toasters).
 2. Create source IP based DNS routing policies with variable secure DNS upstreams. Subnet 1 (admin) uses upstream resolver A, while Subnet 2 (employee) uses upstream resolver B.
 3. Create destination IP based DNS routing policies with variable secure DNS upstreams. Listener 1 uses upstream resolver C, while Listener 2 uses upstream resolver D.
 4. Create domain level "split horizon" DNS routing policies to send internal domains (*.company.int) to a local DNS server, while everything else goes to another upstream.
-5. Deploy on a router and create LAN client specific DNS routing policies from a web GUI (When using ControlD.com).
 
 
 ## OS Support
-- Windows (386, amd64, arm)
-- Windows Server (386, amd64)
+- Windows Desktop (386, amd64, arm64)
 - MacOS (amd64, arm64)
-- Linux (386, amd64, arm, mips)
-- FreeBSD (386, amd64, arm)
-- Common routers (See below)
-
-
-### Supported Routers
-You can run `ctrld` on any supported router. The list of supported routers and firmware includes:
-- Asus Merlin
-- DD-WRT
-- Firewalla
-- FreshTomato
-- GL.iNet
-- OpenWRT
-- pfSense / OPNsense
-- Synology 
-- Ubiquiti (UniFi, EdgeOS)
-
-`ctrld` will attempt to interface with dnsmasq (or Windows Server) whenever possible and set itself as the upstream, while running on port 5354. On FreeBSD based OSes, `ctrld` will terminate dnsmasq and unbound in order to be able to listen on port 53 directly.  
-
-# Install
+- Linux (386, amd64, arm, arm64, mips, mipsle, mips64)
+- FreeBSD (386, amd64, arm, arm64)
+
+## Install
 There are several ways to download and install `ctrld`.
 
 ## Quick Install
 The simplest way to download and install `ctrld` is to use the following installer command on any UNIX-like platform:
 
 ```shell
-sh -c 'sh -c "$(curl -sL https://api.controld.com/dl)"'
+sh -c 'sh -c "$(curl -sL https://api.controld.com/dl?version=client)"'
 ```
 
 Windows user and prefer Powershell (who doesn't)? No problem, execute this command instead in administrative PowerShell:
 ```shell
-(Invoke-WebRequest -Uri 'https://api.controld.com/dl/ps1' -UseBasicParsing).Content | Set-Content "$env:TEMPctrld_install.ps1"; Invoke-Expression "& '$env:TEMPctrld_install.ps1'"
+(Invoke-WebRequest -Uri 'https://api.controld.com/dl/ps1?version=client' -UseBasicParsing).Content | Set-Content "$env:TEMP\ctrld_install.ps1"; Invoke-Expression "& '$env:TEMP\ctrld_install.ps1'"
 ```
 
 Or you can pull and run a Docker container from [Docker Hub](https://hub.docker.com/r/controldns/ctrld)
@@ -80,7 +61,7 @@ docker run -d --name=ctrld -p 127.0.0.1:53:53/tcp -p 127.0.0.1:53:53/udp control
 Alternatively, if you know what you're doing you can download pre-compiled binaries from the [Releases](https://github.com/Control-D-Inc/ctrld/releases) section for the appropriate platform. 
 
 ## Build
-Lastly, you can build `ctrld` from source which requires `go1.21+`:
+Lastly, you can build `ctrld` from source which requires `go1.24+`:
 
 ```shell
 go build ./cmd/ctrld
@@ -99,7 +80,7 @@ docker build -t controldns/ctrld . -f docker/Dockerfile
 ```
 
 
-# Usage
+## Usage
 The cli is self documenting, so feel free to run `--help` on any sub-command to get specific usages. 
 
 ## Arguments
@@ -112,7 +93,7 @@ _/ ___\   __\_  __ \  |   / __ |
      \/ dns forwarding proxy  \/
 
 Usage:
-  ctrld [command]
+  ctrld-client [command]
 
 Available Commands:
   run         Run the DNS proxy server
@@ -128,12 +109,12 @@ Available Commands:
   log         Manage runtime debug logs
 
 Flags:
-  -h, --help            help for ctrld
+  -h, --help            help for ctrld-client
   -s, --silent          do not write any log output
-  -v, --verbose count   verbose log output, "-v" basic logging, "-vv" debug level logging
-      --version         version for ctrld
+  -v, --verbose count   verbose log output, "-v" basic logging, "-vv" debug logging
+      --version         version for ctrld-client
 
-Use "ctrld [command] --help" for more information about a command.
+Use "ctrld-client [command] --help" for more information about a command.
 ```
 
 ## Basic Run Mode
@@ -143,12 +124,12 @@ This is the most basic way to run `ctrld`, in foreground mode. Unless you alread
 
 Windows (Admin Shell)
   ```shell
-  ctrld.exe run
+  ctrld-client.exe run
   ```
 
 Linux or Macos
   ```shell
-  sudo ctrld run
+  sudo ctrld-client run
   ```
 
 You can then run a test query using a DNS client, for example, `dig`:
@@ -161,25 +142,23 @@ You can then run a test query using a DNS client, for example, `dig`:
 If `verify.controld.com` resolves, you're successfully using the default Control D upstream. From here, you can start editing the config file that was generated. To enforce a new config, restart the server. 
 
 ## Service Mode
-This mode will run the application as a background system service on any Windows, MacOS, Linux, FreeBSD distribution or supported router. This will create a generic `ctrld.toml` file in the **C:\ControlD** directory (on Windows) or `/etc/controld/` (almost everywhere else), start the system service, and **configure the listener on all physical network interface**. Service will start on OS boot.
-
-When Control D upstreams are used on a router type device, `ctrld` will [relay your network topology](https://docs.controld.com/docs/device-clients) to Control D (LAN IPs, MAC addresses, and hostnames), and you will be able to see your LAN devices in the web panel, view analytics and apply unique profiles to them. 
+This mode will run the application as a background system service on any Windows, MacOS, Linux or FreeBSD distribution. This will create a generic `ctrld.toml` file in the **C:\ControlD** directory (on Windows) or `/etc/controld/` (almost everywhere else), start the system service, and **configure the listener on all physical network interface**. Service will start on OS boot.
 
 ### Command
 
 Windows (Admin Shell)
   ```shell
-  ctrld.exe start
+  ctrld-client.exe start
   ```
 
 Linux or Macos
   ```
-  sudo ctrld start
+  sudo ctrld-client start
   ```
 
-If `ctrld` is not in your system path (you installed it manually), you will need to run the above commands from the directory where you installed `ctrld`. 
+If `ctrld-client` is not in your system path (you installed it manually), you will need to run the above commands from the directory where you installed it. 
 
-In order to stop the service, and restore your DNS to original state, simply run `ctrld stop`. If you wish to stop and uninstall the service permanently, run `ctrld uninstall`. 
+In order to stop the service, and restore your DNS to original state, simply run `ctrld-client stop`. If you wish to stop and uninstall the service permanently, run `ctrld-client uninstall`. 
 
 ## Unmanaged Service Mode
 This mode functions similarly to the "Service Mode" above except it will simply start a system service and the config defined listeners, but **will not make any changes to any network interfaces**. You can then set the `ctrld` listener(s) IP on the desired network interfaces manually. 
@@ -188,36 +167,36 @@ This mode functions similarly to the "Service Mode" above except it will simply
 
 Windows (Admin Shell)
   ```shell
-  ctrld.exe service start
+  ctrld-client.exe service start
   ```
 
 Linux or Macos
   ```shell
-  sudo ctrld service start
+  sudo ctrld-client service start
   ```
 
-# Configuration
+## Configuration
 `ctrld` can be configured in variety of different ways, which include: API, local config file or via cli launch args. 
 
 ## API Based Auto Configuration
-Application can be started with a specific Control D resolver config, instead of the default one. Simply supply your Resolver ID with a `--cd` flag, when using the `start` (service) mode. In this mode, the application will automatically choose a non-conflicting IP and/or port and configure itself as the upstream to whatever process is running on port 53 (like dnsmasq or Windows DNS Server). This mode is used when the 1 liner installer command from the Control D onboarding guide is executed. 
+Application can be started with a specific Control D resolver config, instead of the default one. Simply supply your Resolver ID with a `--cd` flag, when using the `start` (service) mode. This mode is used when the 1 liner installer command from the Control D onboarding guide is executed. 
 
 The following command will use your own personal Control D Device resolver, and start the application in service mode. Your resolver ID is displayed on the "Show Resolvers" screen for the relevant Control D Endpoint. 
 
 Windows (Admin Shell)
 ```shell
-ctrld.exe start --cd abcd1234
+ctrld-client.exe start --cd abcd1234
 ```
 
 Linux or Macos
 ```shell
-sudo ctrld start --cd abcd1234
+sudo ctrld-client start --cd abcd1234
 ```
 
 Once you run the above command, the following things will happen:
 - You resolver configuration will be fetched from the API, and config file templated with the resolver data
 - Application will start as a service, and keep running (even after reboot) until you run the `stop` or `uninstall` sub-commands
-- All physical network interface will be updated to use the listener started by the service or dnsmasq upstream will be switched to `ctrld`
+- All physical network interface will be updated to use the listener started by the service
 - All DNS queries will be sent to the listener
 
 ## Manual Configuration 
@@ -257,7 +236,7 @@ If you're unable to use a config file, `ctrld` can be be supplied with basic con
 
 ### Example
 ```
-ctrld run --listen=127.0.0.1:53 --primary_upstream=https://freedns.controld.com/p2 --secondary_upstream=10.0.10.1:53 --domains=*.company.int,very-secure.local --log /path/to/log.log
+ctrld-client run --listen=127.0.0.1:53 --primary_upstream=https://freedns.controld.com/p2 --secondary_upstream=10.0.10.1:53 --domains=*.company.int,very-secure.local --log /path/to/log.log
 ```
 
 The above will start a foreground process and:
@@ -266,5 +245,69 @@ The above will start a foreground process and:
 - Excluding `*.company.int` and `very-secure.local` matching queries, that are forwarded to `10.0.10.1:53`
 - Write a debug log to `/path/to/log.log`
 
+## DNS Intercept Mode
+When running `ctrld` alongside VPN software, DNS conflicts can cause intermittent failures, bypassed filtering, or configuration loops. DNS Intercept Mode prevents these issues by transparently capturing all DNS traffic on the system and routing it through `ctrld`, without modifying network adapter DNS settings.
+
+DNS Intercept Mode (`dns`) is the default for new installations on macOS and on Windows desktop editions when no mode is selected with `--intercept-mode` or `service.intercept_mode`; existing Standard installations keep interface DNS mode across upgrades. Windows Server and other platforms keep interface DNS mode unless intercept is selected explicitly. See [Intercept Mode Default](docs/intercept-mode-default.md).
+
+### When to Use
+Enable DNS Intercept Mode if you:
+- Use corporate VPN software (F5, Cisco AnyConnect, Palo Alto GlobalProtect, Zscaler)
+- Run overlay networks like Tailscale or WireGuard
+- Experience random DNS failures when VPN connects/disconnects
+- See gaps in your Control D analytics when VPN is active
+- Have endpoint security software that also manages DNS
+
+### Command
+
+Windows (Admin Shell)
+```shell
+ctrld-client.exe start --intercept-mode dns --cd RESOLVER_ID_HERE
+```
+
+macOS
+```shell
+sudo ctrld-client start --intercept-mode dns --cd RESOLVER_ID_HERE
+```
+
+`--intercept-mode dns` automatically detects VPN internal domains and routes them to the VPN's DNS server, while Control D handles everything else. On macOS and Windows desktop editions the flag can be left out: `dns` is the default. On Windows Server it must be given.
+
+To use interface DNS mode instead, on a new or an existing service:
+
+Windows (Admin Shell)
+```shell
+ctrld-client.exe start --intercept-mode off
+```
+
+macOS
+```shell
+sudo ctrld-client start --intercept-mode off
+```
+
+This removes the intercept rules and reverts to standard interface-based DNS configuration. The selection is persisted (`intercept_mode = "off"` in `ctrld.toml`), so it survives restarts and upgrades.
+
+### Platform Support
+| Platform | Supported | Mechanism |
+|----------|-----------|-----------|
+| Windows  | ✅        | NRPT (Name Resolution Policy Table) |
+| macOS    | ✅        | pf (packet filter) redirect |
+| Linux    | ❌        | Not currently supported |
+
+### Features
+- **VPN split routing** — VPN-specific domains are automatically detected and forwarded to the VPN's DNS server
+- **Captive portal recovery** — Wi-Fi login pages (hotels, airports, coffee shops) work automatically
+- **No network adapter changes** — DNS settings stay untouched, eliminating conflicts entirely
+- **Automatic port 53 conflict resolution** — if another process (e.g., `mDNSResponder` on macOS) is already using port 53, `ctrld` automatically listens on a different port. OS-level packet interception redirects all DNS traffic to `ctrld` transparently, so no manual configuration is needed. This only applies to intercept mode.
+
+### Tested VPN Software
+- F5 BIG-IP APM
+- Cisco AnyConnect
+- Palo Alto GlobalProtect
+- Tailscale (including Exit Nodes)
+- Windscribe
+- WireGuard
+
+For more details, see the [DNS Intercept Mode documentation](https://docs.controld.com/docs/dns-intercept).
+
 ## Contributing
 See [Contribution Guideline](./docs/contributing.md)

cmd/cli/ad_domain.go

@@ -0,0 +1,36 @@
+package cli
+
+import (
+	"strings"
+	"sync/atomic"
+)
+
+// activeDirectoryDomain is the machine's Active Directory domain, recorded when
+// addExtraSplitDnsRule detects it (Windows only; empty elsewhere).
+//
+// Names in it are resolved by the domain controller through upstream.os. The
+// OS resolver races the LAN servers against Control D's public resolver unless
+// the query is marked as a LAN query, and a split-rule match returns before
+// that marking, so without this AD names (DC hostnames, DC-locator SRV
+// records carrying the machine name, WPAD) were sent to 76.76.2.0 in plaintext.
+var activeDirectoryDomain atomic.Pointer[string]
+
+func setActiveDirectoryDomain(domain string) {
+	d := strings.TrimSuffix(strings.ToLower(strings.TrimSpace(domain)), ".")
+	activeDirectoryDomain.Store(&d)
+}
+
+// inActiveDirectoryDomain reports whether name is the AD domain or below it.
+func inActiveDirectoryDomain(name string) bool {
+	d := activeDirectoryDomain.Load()
+	if d == nil || *d == "" {
+		return false
+	}
+	name = strings.TrimSuffix(strings.ToLower(name), ".")
+	return name == *d || strings.HasSuffix(name, "."+*d)
+}
+
+// osUpstreamOnly reports whether upstreams is exactly the OS resolver.
+func osUpstreamOnly(upstreams []string) bool {
+	return len(upstreams) == 1 && upstreams[0] == upstreamOS
+}