Operator and source blocks

Admin only

This page is for the people who run opdns. The pages it describes appear in the dashboard only for accounts flagged as operators (the Operator section of the navigation), and the API routes need the admin scope, which only those accounts can hold. There is no page to grant the flag; opdns-cp admin grant sets it (see Admin tools).

Two lists apply to every profile and to the public path, above anything a user configures:

List	Blocks	Answer
Operator blocks	domain names	NXDOMAIN with Extended DNS Error 15 (Blocked)
Source blocks	client address prefixes	refused before any work (below)

Both are edited on the dashboard’s Operator pages (or /v1/admin/operator-blocks and /v1/admin/source-blocks); operator blocks also from the command line, with opdns-cp admin operator block. Each change is written to object storage in the same database transaction (operator/blocks.json, operator/sources.json), announced to the PoPs with its version and SHA-256, which reload at once, and polled every 30 seconds as a fallback. A PoP refuses a file whose content does not match the announced checksum, or that is older than the announced version, and keeps its current rules, retrying with backoff; refusals are counted in opdns_edge_operator_file_refused_total{file,reason}. Every change is recorded in the audit log. Removed and expired entries are kept, for the record and for the transparency report; Include removed and expired entries shows them.

Both lists apply on the PoPs only. Self-hosted nodes receive neither.

Operator blocks

When to use them is set by the operator blocks and takedowns policy: orders binding on opdns, confirmed abuse against the service or its users, and the designated CSAM list. Never copyright notices or requests outside legal process.

Field	Notes
Pattern	profile rule syntax: example.com blocks the name and everything under it, =example.com only that name, *.example.com only the names under it. Prefer exact names
Reason	one of the three reason codes below
Public reference	the ticket or order id, up to 100 characters; clients see it, and it is the reference in the transparency report
Internal note	approval note and evidence pointers, up to 1,000 characters; never published
PoPs, jurisdictions	scope (below); both empty means fleet-wide
Expires	optional; set it when an order has an end date

Reason codes

Code	For	Scope	What a client sees
legal_order	a court or authority order binding on opdns, reviewed as valid	the issuing jurisdiction	EDE 15, extra text legal_order <reference>
abuse	confirmed malware command-and-control or DGA infrastructure, phishing of opdns itself, names that break the resolver	fleet-wide, with an expiry (at most 30 days by policy)	EDE 15, extra text abuse <reference>
csam	an entry from the designated hotline list	always fleet-wide (the API refuses a scope)	EDE 15, extra text csam and nothing else

The code is the only operator text a client ever sees: the matched pattern never appears in an answer. When several entries share a pattern, the most restrictive code wins (csam, then legal_order, then abuse).

A blocked name is answered NXDOMAIN whatever the profile’s block mode, and it is checked before any profile rule, so an allowlist cannot override it. It is logged like any other query of the profile, with the reason code as the reason, except for csam.

CSAM entries

• A query blocked by a csam entry is never logged. The PoP adds it to the profile’s hourly counters only.
• Clients see no reference.
• The pattern is shown to operators on the admin page and in the admin API and nowhere else: audit entries carry its SHA-256 instead.

Scope

A PoP applies an entry when the entry names that PoP, or names the country the PoP is in (ISO 3166-1 alpha-2, for example FR). It is decided by the answering PoP, not by where the client is: a French court order scoped to FR applies on the PoPs in France, whoever queries them.

Source blocks

For sources abusing the service itself (amplification, floods, scanning). Keep them narrow and temporary: the smallest prefix that stops the abuse, for as long as it lasts.

Field	Notes
Prefix or address	IPv4 no wider than /8, IPv6 no wider than /19; a single address blocks only it
Reason	ticket id and cause, 1 to 200 characters; published to the PoPs, never to clients
PoPs, jurisdictions	as for operator blocks
Expires	7 days by default, at most 90 days ahead; add it again to extend

What a blocked source gets, by transport:

Transport	Result
Plain DNS (UDP, TCP), DNS-over-TLS	REFUSED with EDE 18 (Prohibited), without recursion
DNS-over-HTTPS, DNS-over-HTTP/3, DNS-over-QUIC	the connection is closed after the TLS handshake, without an answer

No query record is written for a blocked source, identified or not; PoP metrics count refusals by reason.

Not built yet

• No page to grant or remove the operator flag.
• The transparency report is a template; it is not generated from these lists yet.
• Self-hosted nodes do not receive either list.