Skip to content
Log inDashboard

Operator and source blocks

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 admin app’s Operator blocks and Source blocks pages (or /v1/admin/operator-blocks and /v1/admin/source-blocks on the admin API), and from the command line with opdns-cp admin operator block and source-block. Check only on the pages (?dry_run=true in the API, --dry-run on the command line) validates a change against the live entries and changes nothing. 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}. The block file is also signed with the list signing key (operator/blocks.json.sig, so the api and the command line need OPDNS_LISTS_KEY_FILE): a PoP refuses an unsigned or badly signed file the same way (reasons unsigned and signature), and deleting the object does not lift the blocks. Each hit is counted per entry id in opdns_edge_operator_block_hits_total{entry} (CSAM entries only in the csam total). 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.

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. What users see and how they appeal a block is explained on the public Operator blocks page.

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
Requester who asked for the block (the court, agency, registry or reporter), up to 200 characters; recorded for the transparency report, never published to the PoPs or to clients
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
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.

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

The Report section of the page (GET /v1/admin/operator-blocks/report, or opdns-cp admin operator block report) counts operator blocks per reason code for a date range: added in it, removed by an operator in it, expired in it, and live at its end. Download CSV (?format=csv, --csv) gives the same table for the transparency report; the rest of the report is written by hand.

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.

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
Action refuse (the default), drop or ratelimit (below)
Rate for ratelimit only: queries per second per client address, 1 to 10,000 (default 5)
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 listed source gets:

Action Plain DNS (UDP, TCP) DNS-over-TLS, HTTPS, HTTP/3, QUIC
refuse REFUSED with EDE 18 (Prohibited), without recursion the connection is closed after the TLS handshake, without an answer
drop no answer at all the connection is closed after the TLS handshake
ratelimit served normally up to the rate per client address (an IPv6 /64 counts as one), the rest dropped served, with the same per-query limit

drop is for floods, where even a REFUSED feeds the attack; ratelimit for a heavy but legitimate source. No query record is written for a refused, dropped or over-the-rate query, identified or not; PoP metrics count them by reason and action (opdns_edge_source_blocked_total{transport,reason,action}). A PoP older than the actions treats every entry as refuse.