Skip to content
Log inDashboard

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.

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

  1. Download the binary for your machine (linux_amd64 for x86-64, linux_arm64 for 64-bit ARM), check it and install it:

    Terminal window
    V=<version>; A=linux_amd64
    curl -fLO https://github.com/operomtl/opdns/releases/download/v$V/opdns_v${V}_$A
    curl -fLO https://github.com/operomtl/opdns/releases/download/v$V/SHA256SUMS
    sha256sum --ignore-missing -c SHA256SUMS
    sudo install -m 0755 opdns_v${V}_$A /usr/local/bin/opdns

    sha256sum must print OK for the file.

  2. 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 unit opdns.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.conf after keeping a copy.

  3. Check it works, and see what it is doing:

    Terminal window
    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).

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.

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 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:

Terminal window
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=false

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

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.

With a self-hosted node, the forwarder can fall back to it when the cloud is out of reach:

Terminal window
sudo opdns config set --node 192.168.1.2 --node-server-name node.home.arpa

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

/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: laptop
transports: [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: true

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