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.
Operator blocks
Section titled “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. 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 |
Reason codes
Section titled “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
Section titled “CSAM entries”- A query blocked by a
csamentry 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.
Report
Section titled “Report”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.
Source blocks
Section titled “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 |
| 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.