Identification
Every query is matched to a profile, and optionally a device, from the transport it arrived on. A transport only ever uses its own source; there is no guessing across them.
| Transport | Profile from | Device from |
|---|---|---|
| DoH, DoH3 | first path segment: https://dns.opdns.net/abc123 |
second segment: /abc123/Living-Room-TV |
| DoT, DoQ | TLS server name: abc123.dns.opdns.net |
prefix before the last hyphen: living-room-tv-abc123.dns.opdns.net |
| Plain DNS over IPv6 | the destination address: the profile id is encoded in the address | none |
| Plain DNS over IPv4 | the source address, if it is a linked IP | none |
Profile ids are case-insensitive: 6 characters, a-z and 0-9, never
000000. Device names are sanitised (letters lowercased, spaces, dots and
underscores to hyphens, other characters dropped, 32 characters max). The
device id is derived from the profile and the name, so the same name on
any PoP or node is the same device.
The IPv6 encoding
Section titled “The IPv6 encoding”Each anycast IPv6 prefix is a /48. Inside it, an address of type 1 carries the profile id as a base-36 number in its low 32 bits:
<48-bit prefix> : 0 : 0 : 1 : <id as base 36, 32 bits>2001:db8:1::1:252c:e35b is profile abc123 in 2001:db8:1::/48The encoding is frozen; an address you configure will keep working. Type 0 is the public path’s service address; other types are refused. The full specification is docs/resolver/ipv6-encoding.md.
When nothing matches
Section titled “When nothing matches”| Case | Result |
|---|---|
Plain DNS from an unlinked address, DoH to / or /dns-query, DoT/DoQ to dns.opdns.net itself or with no server name |
the public path: unfiltered, not logged, rate-limited |
| A well-formed id that is not a profile (any transport) | REFUSED with Extended DNS Error 18 (Prohibited), extra text opdns: unknown profile <id>; never unfiltered |
A DoT/DoQ server name under dns.opdns.net that does not encode a well-formed id (wrong length or characters, a device name joined without its hyphen, a deeper name) |
REFUSED with EDE 18, extra text opdns: malformed profile name |
A DoT/DoQ server name outside dns.opdns.net |
REFUSED with EDE 18, extra text opdns: server name outside the resolver domain |
| An address in the profile IPv6 range whose type is reserved | REFUSED with EDE 18, extra text opdns: invalid profile address |
| A DoH path that is not an id | HTTP 404 |
Only the bare resolver name, or no name at all, takes the public path. Any source that asks for a profile and gets it wrong is refused, so a typo fails loudly on every transport: the device gets no answers rather than unfiltered ones. After any setup, check it works.
A self-hosted node differs in two ways: queries that identify no profile
get the node’s own profile (it serves one profile to the whole network),
and a server name outside the node’s listen.dns_domain is treated the
same way instead of being refused, since the node’s certificate carries
your own names.
Why plain IPv4 cannot name devices
Section titled “Why plain IPv4 cannot name devices”A plain DNS query carries the question and nothing else. On IPv6, the profile’s own addresses tell the resolver which profile was meant; on IPv4 the addresses are shared, so the only signal left is who is asking. opdns has declined to guess devices from addresses (the comparison lists this); encrypted DNS is the way to name devices.