Skip to content
Log inDashboard

Self-hosted node

The self-hosted node, opdns-node, is the same resolver that runs on opdns’s PoPs (server locations): the same listeners and filtering engine in one process, which supervises its own Unbound, with a SQLite file for logs and a small status page. Put it on a Raspberry Pi, a home server or a NAS and point your network at it.

Why run one:

  • It keeps working when the internet or opdns is down. Filtering uses the last profile and lists it received.
  • Logs stay at home. Queries your devices send to the node are logged in its SQLite file and nowhere else.
  • Lower latency for everything on your network.
Enrolled Standalone
Account required none
Profile from the dashboard, pushed to the node over its link in the node’s config file
Lists the signed list artifact opdns publishes the same public artifact
Logs the node’s SQLite; plus the cloud’s logs for the profile if you choose the node’s SQLite
Manage it from the dashboard (logs and analytics are read through the link); a local status page the config file; a local status page
When opdns is unreachable keeps resolving with the last profile and lists unaffected

A node that is neither enrolled nor given a standalone profile does not serve DNS at all: it says how to enrol and exits. Both modes are available today. A standalone node is managed through its profile file and a small local API, with no editing page; see Standalone mode.

Either way, the node answers only devices on your own network unless you allow more; see Network access.

A node serves one profile. Per-client profiles (different profiles for different devices on your LAN) are not available yet. Local names from DHCP leases and private PTR records are answered (Local names).

The node installs a list artifact only if it verifies with a trusted Ed25519 key and matches the announced hash. What the cloud announces is what an enrolled node runs: a lists changed notice over the link, or the lists of a profile pull, installs the named version even when it is older than the one in use. That is how opdns’s rollback of a bad list build reaches your node. An enrolled node installs only versions released to every PoP, never a build still being tried on a few of them.

Every lists changed notice carries the position of the announcement in the cloud’s list stream and says whether it is a rollback. The node applies notices in that order and installs an older version only when the notice says rollback; a notice at or below the last position it applied is a replay or arrived out of order, and is ignored. The last announcement is kept in lists_announced.json in the data directory, so a restart keeps the order. The lists of a profile pull carries no position and never moves the node back. A standalone node never goes back silently: if polling finds an older latest.json than the artifact it has, it refuses it, keeps its current lists and shows the error in opdns-node status.

Updates are small: next to each version opdns publishes signed deltas from the few versions before it. A node that holds one of those versions downloads the delta, rebuilds the new artifact from it and checks that the result is byte for byte the published one (its SHA-256 and its own signature) before installing it. A node further behind, or one whose delta fails for any reason, downloads the full artifact as before. opdns_node_lists_delta_total{result="applied"|"fallback"} and opdns_node_lists_delta_bytes_saved_total on /metrics show how it went. Deltas need the latest.json beside the artifact (or at lists.url) to be readable; otherwise the node downloads full artifacts.

Every published version is also cut into shards, one per protection group (ads and trackers, malware and phishing, scams and abuse, newly registered domains, device telemetry, each parental group), each a signed artifact of its own. Set lists.memory_budget_mb (OPDNS_LISTS_MEMORY_BUDGET_MB) to the memory, in MiB, the lists may take, and the node loads only the shards holding a list your profile can turn on (schedules included), merged into one index, instead of the full artifact. When the profile changes, the node fetches the shards it now needs. If the profile needs more than the budget, the node loads them anyway, so protection never silently drops, and warns: in its log, on the status page (opdns-node status --json shows shards, need_bytes and over_budget) and on /metrics (opdns_node_lists_over_budget 1, opdns_node_lists_shard_bytes). 0, the default, loads the full artifact.

The index is memory-mapped: what it takes is the size of its file, and the kernel can page it out under pressure like any cache. Sizes for the current catalogue (modelled from each source’s size; the full artifact is smaller than all shards together because a shard sizes its hash table on its own):

Shard Lists Entries Size (MiB)
ads_trackers 7 304 894 9.5
malware_phishing 3 2 387 662 81.8
scams_abuse 2 17 500 0.6
nrd 1 6 184 206 246.2
telemetry 14 674 0.0
affiliate_links 1 17 0.0
adult 9 989 083 34.5
gambling 1 572 111 18.5
social 18 4 941 0.2
entertainment 23 37 537 1.2
other 8 79 213 2.5
all shards 10 577 838 395.1
Profile Shards loaded Entries List memory (MiB)
New profile (every slider at step 3) ads_trackers, malware_phishing, scams_abuse 2 710 056 92.0
Every slider at step 4 ads_trackers, malware_phishing, scams_abuse 2 710 056 92.0
Every slider at step 5 ads_trackers, malware_phishing, scams_abuse, nrd 8 894 262 338.2

A new profile fits a 512 MB router with room to spare. The newly registered domains list, on the scams and abuse slider’s last step, is by far the largest shard: on a 512 MB device keep that slider at step 4 or below, or give the node more memory. The parental groups load only when you turn them on.

An enrolled node checks that the profile it receives comes from opdns: every profile the cloud sends is signed with Ed25519 (profile_signature over the profile’s id, version and content). The node trusts:

  • the keys the cloud announces: at enrolment, then in every profile response that verifies, so a key rotation needs nothing from you. Learnt keys are kept in <data_dir>/profile_keys.json, backed up with the node and forgotten on unenrol;
  • the keys you pin with cloud.profile_public_keys (OPDNS_CLOUD_PROFILE_PUBLIC_KEYS, hex), if you want trust not to depend on what the node learnt at enrolment.

Once any key is trusted, an unsigned or badly signed profile is refused: the node keeps resolving with its last good profile, opdns-node status and the local page show the error, and opdns_node_profile_signature_failures_total counts it. A key the cloud stops announcing stays trusted until the next pull confirms the new set.

The first key is trusted on first use: a node enrolled through a compromised path would learn the wrong key, which is what pinning prevents. If opdns’s key is ever lost and replaced, stop the node, delete profile_keys.json, and start it again so it learns the new key.

An enrolled node enforces the same operator blocks as opdns’s own servers: domains blocked for a legal order or for abuse are answered NXDOMAIN with extended DNS error 15 (Blocked) and the public reason and reference (for example legal_order ORDER-1), whatever your profile says, and sources blocked for abuse are refused. The blocks come with every profile pull, signed with the profile signing key and checked like the profile; a change reaches the node within seconds over the link. The node keeps the last set in operator_blocks.json and operator_sources.json in the data directory and enforces it while offline and after a restart; a block stops applying at its expiry even offline. The local page and opdns-node status --json show the versions in force. Your node gets the blocks that apply everywhere and those for the country it links from; blocks limited to one of opdns’s PoPs do not reach it. Standalone nodes do not receive operator blocks yet.

The node answers your network’s own names itself, in both modes, without asking the internet:

  • Local domains, local.domains (default home.arpa, RFC 8375): hosts from local.hosts (name=address[,address], a bare label is answered under every local domain) and host names from DHCP lease files in local.lease_files (dnsmasq, ISC dhcpd or Kea CSV, detected; polled every local.lease_poll, 30 seconds). Static hosts win over leases. local.hosts is reloaded on SIGHUP.
  • Reverse lookups of private addresses (RFC 1918, 169.254/16, fc00::/7, fe80::/10): PTR answers from the same table.

A name or private address the node does not know is answered NXDOMAIN locally, or asked of your router when local.forward names it (conditional forwarding). Either way, private reverse lookups never leave your network. Local names are answered after the profile’s policy, so a rewrite of the same name still wins over them. The local page shows how many names are answered and when the leases were last read.

The default is on with nothing configured: home.arpa names you have not declared get NXDOMAIN, and reverse lookups of private addresses are kept local. A local domain outside home.arpa, .lan, .home, .internal and the other local suffixes may be caught by rebinding protection. With local.device_names on (the default), queries from clients that send no device name are logged under their lease or host name (Logs on your node).

Unbound can ask authoritative servers over IPv4 and IPv6. On a host without working IPv6, trying IPv6 first makes cold lookups slow and failures more frequent, so the node checks the host at start and on every reload (SIGHUP): it asks the kernel for a route to a public IPv6 address, without sending a packet.

The host has Unbound is told
no IPv6 route IPv4 only (do-ip6: no)
a route, but only a private or unique-local IPv6 source address prefer IPv4 (prefer-ip4: yes), as opdns’s PoPs do without a public IPv6 source
a public IPv6 source address both families

unbound.ipv6 overrides the check: auto (default), on, prefer-ip4 or off. A change of the result restarts Unbound. The local page and /api/status (unbound.ipv6) show the route, the source address and what Unbound uses. This concerns only the node’s own queries to the internet (and only a node that runs its own Unbound, not one with unbound.spawn: false); your devices can still query the node over IPv6.

Like every opdns PoP, the node’s Unbound keeps its own copy of the DNS root zone (RFC 8806), on by default. Root referrals come from the copy, so a lookup that is not cached starts at the top-level domain’s servers instead of asking a root server: slightly faster, and while the copy is valid the root servers do not see which top-level domains your network looks up.

  • The copy is <data_dir>/unbound/root.zone (about 2 MB). Unbound refreshes it on the zone’s own timers, from the sources in dns.root_zone_sources: by default the root servers that allow transfers (b, c, d, f, g and k, plus ICANN’s xfr.lax and xfr.cjr, over IPv4 and IPv6), by IP address. Host names and URLs are refused.
  • Every copy is checked against its ZONEMD digest (and its DNSSEC signatures while validation is on) before it is used.
  • A missing, rejected or expired copy never stops resolution: Unbound asks the root servers, as any resolver does. /healthz does not depend on it.
  • The status page and opdns-node status show the copy’s serial and age (unbound.root_zone in /api/status) and warn once it is two days old; the root zone normally changes about twice a day. /metrics has opdns_edge_root_zone_loaded, opdns_edge_root_zone_serial and opdns_edge_root_zone_updated_timestamp_seconds, the same series as the PoPs.

Transfers need outbound TCP port 53 (to the addresses) and HTTPS (to the URL). On a network that only lets DNS out to one server, set dns.root_zone_sources to a local server that serves the root zone by zone transfer, or turn the copy off with dns.root_zone: false (the environment variables are OPDNS_DNS_ROOT_ZONE and OPDNS_DNS_ROOT_ZONE_SOURCES). Both keys take effect on restart; see the configuration reference. A node with unbound.spawn: false ignores them.

  • Linux on amd64 or arm64 with Docker, or the static binary for linux/amd64, linux/arm64 or darwin/arm64. On Linux the binary runs as a hardened systemd service (the unit file).
  • For the binary: Unbound installed on the host. The container includes it.
  • Nothing to configure for an enrolled node: the list signing key comes from the cloud.
  • Port 53 (UDP and TCP) free on the host, and 8053 for the status page.
  • Memory: the full list artifact takes about 300 MB and is sized for under 1 GB. On a router or a board with 512 MB or 1 GB, set a memory budget so the node loads only the lists its profile uses (Small hardware).

From an enrolled node, over its one outbound connection to link.opdns.net: the node’s id; its versions (node, Unbound, profile, lists); uptime and last sync time; SQLite file size, oldest record time and pending and dropped record counts; clock offset and whether Unbound is healthy; connection times and its public IP address. Never the queries it resolves or the logs it produces, except as answers to your own dashboard requests (relayed through opdns in transit, not stored). When such an answer lists destination addresses, opdns adds their countries on the way, since the node has no GeoIP data (Analytics from your node).

From a standalone node: downloads of the public list artifact (IP address and time), kept 14 days in operational logs.

The details, arranged by mode, are in Privacy of your node; the binding text is the privacy policy, section 7. How the link works is on Architecture.

The node is source-available under the Source First License 1.1: free for non-commercial use such as your home network. A business running it needs a commercial licence. See Licensing and the self-hosted licence FAQ.

Next: install with Docker or the static binary.