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).
List updates and rollbacks
Section titled “List updates and rollbacks”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.
Small hardware: list shards
Section titled “Small hardware: list shards”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.
Profile signing keys
Section titled “Profile signing keys”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.
Operator blocks
Section titled “Operator blocks”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.
Local names
Section titled “Local names”The node answers your network’s own names itself, in both modes, without asking the internet:
- Local domains,
local.domains(defaulthome.arpa, RFC 8375): hosts fromlocal.hosts(name=address[,address], a bare label is answered under every local domain) and host names from DHCP lease files inlocal.lease_files(dnsmasq, ISC dhcpd or Kea CSV, detected; polled everylocal.lease_poll, 30 seconds). Static hosts win over leases.local.hostsis reloaded onSIGHUP. - 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).
IPv6 for upstream queries
Section titled “IPv6 for upstream queries”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.
Local root zone
Section titled “Local root zone”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 indns.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.
/healthzdoes not depend on it. - The status page and
opdns-node statusshow the copy’s serial and age (unbound.root_zonein/api/status) and warn once it is two days old; the root zone normally changes about twice a day./metricshasopdns_edge_root_zone_loaded,opdns_edge_root_zone_serialandopdns_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.
What you need
Section titled “What you need”- Linux on
amd64orarm64with Docker, or the static binary forlinux/amd64,linux/arm64ordarwin/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).
What opdns learns from your node
Section titled “What opdns learns from your node”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.
Licence
Section titled “Licence”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.