Command line (opdns CLI)
opdns is a small DNS forwarder. It answers on 127.0.0.1:53 and [::1]:53
and sends every query to opdns over encrypted DNS, with your profile id and
a device name. Use it where the system has no encrypted DNS setting of its
own (Windows 10, most Linux without systemd-resolved, routers), or when you
want more than the setting gives you:
- Every transport, with fallback. DNS-over-HTTPS over HTTP/3, then over HTTP/2, then DNS-over-TLS, then DNS-over-QUIC: if a network blocks one, the next one answers, and the faster one is tried again in the background.
- A device name from the host name, or the name you choose.
- Named LAN devices on a router: each device behind it appears under its own name in your logs.
- Local names forwarded to your router (
home.arpa, a company domain). - Captive portals in hotels and cafés still show their login page.
- A self-hosted node to fall back to at home.
Where the system already speaks encrypted DNS (Android, iOS, macOS, Windows 11, systemd-resolved, the browsers), its own setting needs no software: see the other setup guides.
Install
Section titled “Install”You need: your profile id (the dashboard’s Setup page), and administrator rights: the forwarder binds port 53 and sets the system’s resolver.
The binaries are on the releases page,
named opdns_v<version>_<os>_<arch>, next to a SHA256SUMS file that
lists the checksum of every file in the release. In the commands below,
replace <version> with the newest version on that page, without the
leading v (for example 0.1.23 for v0.1.23).
-
Download the binary for your machine (
linux_amd64for x86-64,linux_arm64for 64-bit ARM), check it and install it:Terminal window V=<version>; A=linux_amd64curl -fLO https://github.com/operomtl/opdns/releases/download/v$V/opdns_v${V}_$Acurl -fLO https://github.com/operomtl/opdns/releases/download/v$V/SHA256SUMSsha256sum --ignore-missing -c SHA256SUMSsudo install -m 0755 opdns_v${V}_$A /usr/local/bin/opdnssha256summust printOKfor the file. -
Install it as a service for your profile:
Terminal window sudo opdns install --profile <profile-id>This writes
/etc/opdns/client.yaml, installs and starts the systemd unitopdns.service, and, while the service runs, points the system at it: with systemd-resolved through a drop-in (/etc/systemd/resolved.conf.d/opdns.conf), otherwise by replacing/etc/resolv.confafter keeping a copy. -
Check it works, and see what it is doing:
Terminal window opdns status
-
Download the binary, check it and install it. Use
curlin Terminal, as here, rather than a browser, so that macOS does not block it as an unsigned download. The binary is for Apple silicon; on an Intel Mac, build it from source as in the Windows tab, withGOOS=darwinand-o opdns.Terminal window V=<version>; A=darwin_arm64curl -fLO https://github.com/operomtl/opdns/releases/download/v$V/opdns_v${V}_$Acurl -fLO https://github.com/operomtl/opdns/releases/download/v$V/SHA256SUMSgrep " opdns_v${V}_$A\$" SHA256SUMS | shasum -a 256 -csudo mkdir -p /usr/local/binsudo install -m 0755 opdns_v${V}_$A /usr/local/bin/opdnsshasummust printOKfor the file. -
Install it as a launchd daemon for your profile:
Terminal window sudo opdns install --profile <profile-id>This writes
/etc/opdns/client.yamland/Library/LaunchDaemons/io.opdns.client.plist, starts it, and, while it runs, sets the DNS servers of every network service to127.0.0.1and::1(networksetup); stopping it puts back what was there. -
Check it works and run
opdns status.
If you also installed the opdns configuration profile, remove it first (System Settings → General → Device Management): the profile’s encrypted DNS takes precedence over the forwarder.
-
No Windows binary is published yet: build
opdns.exefrom source on any computer with Go 1.27 or newer. Download the Source code archive of the newest release from the releases page, unpack it, and in the unpacked folder run:Terminal window CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -o opdns.exe ./cmd/opdnsThat line is for a Linux or macOS shell. In PowerShell on Windows itself, run
$env:CGO_ENABLED='0'; go build -trimpath -o opdns.exe ./cmd/opdnsinstead. Copyopdns.exetoC:\Program Files\opdns\opdns.exeon the Windows computer. -
In an administrator PowerShell:
Terminal window & 'C:\Program Files\opdns\opdns.exe' install --profile <profile-id>This writes
C:\ProgramData\opdns\client.yaml, installs and starts the Windows service opdns DNS forwarder, and, while it runs, sets every connected adapter’s DNS servers to127.0.0.1and::1(netsh); stopping it puts back DHCP or the addresses you had. -
Check it works and run
opdns status.
The device name is the host name’s first label (Annas-MacBook.local
becomes annas-macbook); choose another with --device. Names follow the
resolver’s rules (Your endpoints).
What it sends
Section titled “What it sends”For profile abc123 and device laptop, the forwarder uses, in this
order:
| Transport | Address |
|---|---|
| DNS-over-HTTPS, HTTP/3 then HTTP/2 | https://dns.opdns.net/abc123/laptop |
| DNS-over-TLS (port 853) | laptop-abc123.dns.opdns.net |
| DNS-over-QUIC (port 853) | laptop-abc123.dns.opdns.net |
It looks up dns.opdns.net once, through the resolver your network
gave you (the one in use before activation), and keeps its connections
open between queries. Answers are cached for their TTL. A transport that
fails is skipped for 15 seconds, then for twice as long each time it
fails again (at most 5 minutes); it is tried again in the background, on
the unfiltered public path, never by delaying one of your queries. A move
to another network starts afresh. Change the order or leave transports out
with --transports doh2,dot.
Start, stop, activate
Section titled “Start, stop, activate”| Command | Does |
|---|---|
opdns status |
the service, the transport in use, every transport’s state, the cache, the counters |
opdns stop / opdns start |
stop or start the service; stopping restores the system resolver |
opdns deactivate |
put the system resolver back, leaving the forwarder running |
opdns activate |
point the system resolver at the forwarder again (refused when it does not answer) |
opdns config |
the effective configuration; opdns config set --device tv changes the file |
opdns run |
run in the foreground, for testing or your own init system |
opdns uninstall |
stop, restore the system resolver, remove the service (--purge also the config) |
To run the service without it touching the system resolver, install with
--auto-activate=false and point programs at 127.0.0.1 yourself.
On a router
Section titled “On a router”On a router or a small server for the whole network, listen on the LAN side and name the devices behind it, from the DHCP lease file (dnsmasq, ISC dhcpd, Kea) or by address:
sudo opdns install --profile <profile-id> --device home-router \ --listen 192.168.1.1:53 --listen 127.0.0.1:53 \ --lease-file /tmp/dhcp.leases \ --client 192.168.1.20=kids-tablet \ --forward home.arpa=192.168.1.1 \ --auto-activate=falseThen hand out the router’s address as the DNS server (usually already the
case) and disable the router’s own resolver on that address. Each device
appears in the logs under its lease name (--client wins); one without a
name appears as the router’s device. --forward sends a domain’s names to
another server in plain DNS: the router’s home.arpa names never leave
your network.
There is no OpenWrt or other router package yet. On an ARM64 router, use
the linux_arm64 binary; for another architecture, build it from the
release’s source code as in the Windows tab, for example with
GOOS=linux GOARCH=mipsle (most MT7621 routers). Then start opdns run
from the router’s init system with the same flags: opdns install
supports systemd, launchd and Windows only.
Captive portals
Section titled “Captive portals”When no transport answers, the forwarder checks whether a captive portal
holds the network. If one does, it asks the network’s own resolver, in
plain DNS, for the names your system uses to detect portals (Apple’s,
Android’s, Windows’, Firefox’s, NetworkManager’s) and the portal’s own
host, so the login page appears. Nothing else is resolved until you are
through; then it is back on encrypted DNS within seconds. Turn this off
with --captive-portal=false.
A self-hosted node at home
Section titled “A self-hosted node at home”With a self-hosted node, the forwarder can fall back to it when the cloud is out of reach:
sudo opdns config set --node 192.168.1.2 --node-server-name node.home.arpaIt is tried after every cloud transport, over DNS-over-TLS (or plain DNS
with --node-transport dns). The node’s certificate must be valid for the
server name; for a private one add its root with --ca-file.
The config file
Section titled “The config file”/etc/opdns/client.yaml (C:\ProgramData\opdns\client.yaml) holds the
same keys as the flags; every flag also has an OPDNS_* environment
variable (opdns --help):
profile: <profile-id>device: laptoptransports: [doh3, doh2, dot, doq]listen: ["127.0.0.1:53", "[::1]:53"]forward: ["home.arpa=192.168.1.1"]clients: ["192.168.1.20=kids-tablet"]lease_files: [/tmp/dhcp.leases]node: { addr: 192.168.1.2, server_name: node.home.arpa }auto_activate: truePrivacy
Section titled “Privacy”The forwarder’s logs never carry the names you look up or your devices’
addresses. --log-queries adds one line per query with its name, for
debugging on your own machine. Status and Prometheus metrics are served on
127.0.0.1:9853 only (--metrics off turns them off).