Admin tools
The admin host
Section titled “The admin host”The operator tools are not part of the dashboard or the public API. They
are the admin app on the admin host, which is reachable only from the
operators’ private network. Its address is in the admin runbook in the
operator repository, not on this public site. The app and its API
(/v1/... on the same host) are served by the control plane’s
admin-api role. app.opdns.io and api.opdns.io have no operator page
and no /v1/admin route (they answer 404).
- Sign in with your op account. The admin app signs you in through opauth (the account service shared by the opr products) and checks that the account is opauth staff, that you signed in with a second factor and that this was less than 8 hours ago. Otherwise it shows why (not staff, second factor required, sign-in too old) and does not start a session. There is no password, authenticator or passkey sign-in on the admin host itself.
- Its own sessions. An admin session is valid on the admin host only, lasts at most 8 hours from your sign-in at opauth and ends after an hour unused; a dashboard session is not valid there, nor an admin session on the dashboard. There are no API tokens on the admin API.
- Writes ask twice. Every action that changes something opens a
confirmation first; the ones that change accounts, profiles or the
signup gate also need a sign-in within the last five minutes, and the
app sends you through opauth’s sign-in again when it is older
(
403 reauth_required). Every action is in the operator audit.
Operator accounts
Section titled “Operator accounts”Being an operator is being opauth staff. Staff are granted and revoked in opauth’s own admin console, not in opdns: opdns has no operator flag, no command or route that grants one, and the public API never makes an account an operator. Revoking someone’s staff access stops their next sign-in; signing them out at opauth ends their admin sessions too.
opdns-cp admin operator holds the actions operators take:
block and source-block.
The command line talks to the database directly and needs no sign-in.
Profiles from the command line
Section titled “Profiles from the command line”opdns-cp admin profile reads and changes customer profiles, for support
and incidents. Writes go through the same write path as the API (version
bump and outbox row in one transaction, so the change is published to the
PoPs like any other) and are audited as profile.create or
profile.update, with the before and after values, the actor
cli:<user>@<host> and the optional --reason.
opdns-cp admin profile get abc123 --documentopdns-cp admin profile set abc123 settings.block_mode=refused --reason "ticket 812" --yes| Subcommand | Does |
|---|---|
list [--email X] [--all] [--limit 50] |
profiles across accounts, newest first (--all includes deleted ones) |
get ID [--document] |
a profile as JSON, or with --document the document the publisher sends to the PoPs (rules, lists, linked IPs) |
create --email X [--name N] |
a new profile for that account |
set ID [--version N] [--json BODY | --file F | KEY=VALUE...] |
a partial update, the body of PATCH /v1/profiles/{id}; KEY is name or section.field (security, parental, settings), VALUE JSON or a bare string; --version fails the write if the profile changed since you read it |
The profile pipeline itself (stream, replay, reconcile) has its own commands: Profile propagation.
Suspend a profile
Section titled “Suspend a profile”Until it is reinstated, the edges and the profile’s self-hosted nodes
answer every query of a suspended profile REFUSED with Extended DNS
Error 15 (Blocked) and the text profile suspended, or
profile suspended: <public reason>, unlogged. What the
customer sees is on
Profiles.
A suspension has two texts:
--reason(reason) is the internal note: ticket ids, report numbers. It is never shown to the customer: not in DNS answers, the dashboard, the API, their audit log or their data export.--public-reason(public_reason) is optional and is shown to the profile’s users, in every refused answer and on their dashboard: one short plain sentence (at most 120 printable characters), free of private detail.
opdns-cp admin profile suspend abc123 --reason "abuse ticket 812" \ --public-reason "terms of service violation, contact support" --yesopdns-cp admin profile unsuspend abc123 --yes| Subcommand | Does |
|---|---|
suspend ID --reason R [--public-reason P] |
suspends the profile; the reason is required, the public reason optional |
unsuspend ID [--reason R] |
reinstates it (both texts are cleared) |
The same from the admin app (Profiles, Suspend… on a row) or the
admin API: GET /v1/admin/profiles/{id} returns the operator view (suspended,
suspended_reason, suspended_at, suspended_by, suspended_public_reason), and
PATCH /v1/admin/profiles/{id} with
{"suspended": true, "reason": "…", "public_reason": "…"} (the reason is
required to suspend, at most 200 characters; the public reason optional,
at most 120; both ignored when reinstating) changes it. Changing only the
public reason of a suspended profile is a new version too. Rename… on the same
row (PUT /v1/admin/profiles/{id}/name) renames a profile through the
path of admin profile set ID name=…, audited as profile.update. Both
need a sign-in within the last five minutes.
Either way the change goes through the profile write path (new version, outbox row), so every PoP and enrolled node applies it within seconds like any profile change. On them the profile compiles to no lists, rules, rewrites, security or parental controls, with logs off, no client subnet and no cache boost; it keeps its id, linked IPs and retention, and the edge writes neither a log record nor a counter for it. Operator blocks still apply. A request that changes nothing (suspending a suspended profile) writes nothing and says so.
Each change is audited as profile.suspended or profile.unsuspended in
the profile’s organisation. The reason (and the previous one) is in the
operator audit only: the customer’s Activity shows the entry without it,
and the reason never reaches the profile API, the node’s document or the
customer’s data export. While suspended, the customer’s writes to the
profile get 409 profile_suspended; admin profile set, DDNS updates by
token and a node’s own calls still work. A self-hosted node older than
this feature refuses the document with the new fields and keeps its last
one, so it goes on filtering.
Operator blocks from the command line
Section titled “Operator blocks from the command line”The operator blocks of the admin app can also be managed without the API:
opdns-cp admin operator block listopdns-cp admin operator block add --pattern example.com --reason-code legal_order \ --public-ref "ORDER-2026-17" --requester "Tribunal judiciaire de Paris" \ --jurisdictions FR --expires-in 720h --yesopdns-cp admin operator block remove <id> --yesopdns-cp admin operator block report --from 2026-07-01 --to 2026-09-30 --csv
opdns-cp admin operator source-block listopdns-cp admin operator source-block add --cidr 192.0.2.0/24 --reason "ABUSE-31 flood" \ --action drop --expires-in 24h --yesopdns-cp admin operator source-block remove <id> --yesblock add takes --pattern, --reason-code (legal_order, abuse or
csam), and optionally --public-ref (the legal reference clients see),
--requester (who asked; never published), --note, --pops,
--jurisdictions and --expires-in. source-block add takes --cidr,
--reason, --action (refuse, drop or ratelimit, with
--rate-limit-qps), --pops, --jurisdictions and --expires-in (7
days by default, at most 90). list --all includes removed and expired
entries, --json prints JSON. --dry-run on add and remove checks the
change against the live entries (a duplicate still fails) and changes
nothing; it needs neither --yes nor a destination. block report counts
operator blocks per reason code for a date range (--from, --to
inclusive, UTC; --csv or --json). A change writes the row,
operator/blocks.json or operator/sources.json and the audit entry
(admin.operator_block_created, admin.source_block_removed, …) in one
transaction, through the same code path as the admin API, then announces it to the PoPs over NATS (--nats-url;
without NATS they pick the file up by polling). The file goes to the
--s3-* bucket, or --export-dir without one, as for the api role.
Outside env=dev, every admin write (profile create|set|suspend|unsuspend, operator block add|remove, profiles republish,
operator source-block add|remove, profiles reconcile --fix) refuses to
run without --yes.
List reports from the command line
Section titled “List reports from the command line”opdns-cp admin list-reports export --accepted turns the list reports
operators accepted into candidate lines for the list repository; it is
read-only. See List reports.
Operator audit
Section titled “Operator audit”Audit in the admin app is every organisation’s audit log,
newest first, read-only: sign-ins, credential and token changes, profiles,
nodes, exports, deletions and operator actions. Filter it by actor (exact,
such as account:<id> or cli:<user>@<host>), by action (exact, such as
auth.login_failed, or a prefix ending in ., such as admin.), and by a
time range; the filters are kept in the address, so a filtered view can be
shared. Load more fetches older entries.
The API is GET /v1/admin/audit on the admin API with actor, action,
from, to and the usual limit and cursor. An organisation’s own
members see only their organisation’s entries, on
Account → Activity.
Operator overview
Section titled “Operator overview”Overview in the admin app is the fleet at a glance, over the last 30 days (UTC, today included): accounts (total, new per day, scheduled for deletion), live profiles (and how many are suspended), enrolled self-hosted nodes and how many are online, queries per day with the blocked share and the error rate, each PoP’s queries, median and 95th percentile resolution time, and blocked queries by list category. The numbers are totals across every organisation: nothing on the page is per account, per profile or per domain, and there are no query logs.
Queries per day come from the always-on hourly counters, so they include profiles with logs off. The per-PoP and per-category numbers come from logged queries only (two daily rollups in ClickHouse that hold no profile, device or name); profiles with logs off are not in them. The answer is computed at most every five minutes and shared by every operator; the page says when. Without ClickHouse the traffic half says so and the account, profile and node counts still show.
The API is GET /v1/admin/analytics/overview.
Operator accounts and profiles
Section titled “Operator accounts and profiles”Accounts in the admin app lists every account, newest first: address, organisation, created, last sign-in, live profiles and state (Active, Unverified, Suspended when one of its profiles is suspended, Deletion scheduled). Search by address, organisation name or account id, and filter by suspension, scheduled deletion and creation date; the filters are kept in the address. An account’s page shows its profiles (with enrolled and online node counts), how many API tokens and passkeys it has, whether an authenticator app is on, and the operator actions that exist for it, each behind a confirmation and audited:
| Action | Does | API (admin host) | Audit |
|---|---|---|---|
| Schedule deletion… / Cancel deletion… | deletion on the owner’s behalf, with the reason and the data-rights ticket (see the deletion-request-by-email runbook; the same seven-day cooling-off as a deletion the owner starts) | POST / DELETE /v1/admin/accounts/{id}/deletion |
admin.deletion_requested, admin.deletion_canceled |
| Suspend… / Reinstate | suspends (or reinstates) every live profile of the account, each as Suspend a profile does; the reason is required to suspend | POST /v1/admin/accounts/{id}/suspension |
profile.suspended, profile.unsuspended (one per profile) |
| Resend verification email | a new address verification link to an unverified account (409 already_verified otherwise) |
POST /v1/admin/accounts/{id}/verification |
admin.verification_resent |
All of them need a sign-in within the last five minutes. The command
line equivalents are opdns-cp admin account delete|undelete|suspend|unsuspend
(operator access itself is opauth’s, Operator accounts).
Profiles in the admin app lists every live profile, newest first: id, name, owning account (a link to its page), created, enabled lists, nodes and suspension. Search by profile id (its first characters), name or the account’s address.
Apart from the actions above they are read-only. They show no
passwords, tokens, client addresses or logs. Every page view, search and
account opened is written to the operator audit log as admin.viewed
with what was viewed (and the search text), in the operator’s
organisation, and reads are limited to 120 a minute per operator. The
API is GET /v1/admin/accounts (q, operator, suspended,
pending_deletion, created_from, created_to), GET /v1/admin/accounts/{id} and GET /v1/admin/profiles (q, suspended).
Operator feedback
Section titled “Operator feedback”Feedback in the admin app is the inbox of the messages users send from
Account → Help and feedback in the last 365 days, newest first, in
tabs by status with their counts: New (new and reopened messages),
Acknowledged, Resolved and All; the arrow keys move between tabs.
Each row shows when it arrived, its category (Bug, Idea, Question,
Other), the message, the dashboard page it was sent from (ids replaced,
such as /p/:id/logs), the sender’s account hash (never the address
in the list; the first 12 hex digits of the SHA-256 of the account id, the
pseudonym of the API’s access log), its status and how many replies and
notes it has. no reply wanted under the hash means the sender unticked
the reply option. Search by a piece of the message or the page (case
insensitive), or by an account id or account hash (exact), and filter by
category; the tab and filters are kept in the address.
Open a message to work on it. Its page shows the whole message, the sender’s account (address, organisation, plan, state, linked to the account’s page) and:
- Status: Acknowledge a new or reopened message, Resolve it when
handled, Reopen a resolved one. The latest of each, with when and by
whom, is shown. Keys outside text fields:
a,r,o. - Reply by email: write a subject (default “Re: your feedback on
opdns”) and a message, Preview it as the sender will read it (your
message, the signature, a short quote of theirs), then Send email.
It goes through the mail queue from opdns’s sender address with the
support mailbox as Reply-To, so their answer reaches support. Replying
acknowledges a new message. Each sent reply is listed with its delivery
(Queued, Sent, Failed, Suppressed). No reply can be sent when the
sender asked for none.
efocuses the message; Ctrl+Enter previews. - Internal notes: only staff see them; they cannot be edited or
removed.
nfocuses the note; Ctrl+Enter adds it.
Every view and search is written to the operator audit log as
admin.viewed (target feedback with the search text and filters, or
feedback:<id> for one message), reads are limited to 120 a minute per
operator, and every write is audited with the staff member as actor:
admin.feedback_acknowledged, admin.feedback_resolved,
admin.feedback_reopened, admin.feedback_noted (the note’s id, not its
text) and admin.feedback_replied (target feedback:<id>). The API is
GET /v1/admin/feedback (q, category, status, repeatable, limit,
cursor; with counts per status), GET /v1/admin/feedback/{id}, and
POST /v1/admin/feedback/{id}/acknowledge, /resolve, /reopen,
/notes ({"body": "..."}) and /replies ({"subject": "...", "message": "..."}). Messages, notes and replies are deleted with the
sender’s account.
Operator waitlist
Section titled “Operator waitlist”While signup is invite-only, people join the waitlist from the site and confirm their address by email. Waitlist in the admin app lists the confirmed entries, newest confirmation first: the address, the first digits of its SHA-256 hash, when it confirmed, when it was invited, and the state of its invitation code: Unused, Used, Expired or Revoked (Not invited before the first invitation). Entries that have not confirmed are not listed. An entry leaves the waitlist when its address signs up. Search by entry id, or by at least four hex digits of the address hash (the form the audit log records addresses in); addresses themselves are not searchable, so they never end up in a URL or an access log.
- Invite on a row sends that address an invitation at once. A row already invited says Invite again… and asks first: a new code is sent, and the earlier one keeps working until it is used or expires.
- Invite next N (10 by default, at most 100) invites the confirmed entries that were never invited, first confirmed first. The confirmation says how many will be invited (all that wait when fewer than N do).
Each invitation is a signup invite code that works once and expires after
30 days, recorded on the entry, and the Your invitation to the opdns
alpha email with the signup link (/signup#invite_code=…), queued
through the mailer like every other email. A code whose email could not be
queued is revoked at once and the row shows it as Revoked: invite it
again. Without a mail provider, the page refuses to invite (503 mail_unavailable); use opdns-cp admin waitlist invite, which prints the
code for manual delivery.
Every page view and search is audited as admin.viewed (target waitlist), and each
invitation batch as one admin.waitlist_invited row in the operator’s
organisation with the number invited and the entry ids. The API is GET /v1/admin/waitlist (q, limit, cursor) and POST /v1/admin/waitlist/invite with {"ids": [...]} or {"next": N}. The
command line equivalent, by address, is opdns-cp admin waitlist list | invite | delete (see the admin runbook).
Signup mode and invitations
Section titled “Signup mode and invitations”Signup in the admin app shows the signup gate in effect (Open,
Invite only or Closed), whether it is an operator’s choice or the
deployment’s default (OPDNS_SIGNUP_MODE), and lets you change it, or
go back to the default, at once on every API replica. Below it, the
signup invitations: uses, remaining uses, expiry, whether revoked, and
the note. New invitation… mints a code (one use by default, an
optional expiry such as 48h or 7d, a note) and shows it once, with a
copy button: it is not stored in the clear and cannot be shown again.
Revoke… stops a code admitting further signups.
The API is GET and PUT /v1/admin/signup/mode ({"mode": "invite"},
or "default"), GET and POST /v1/admin/signup/invites and DELETE /v1/admin/signup/invites/{id}, audited as admin.signup_mode_set,
admin.signup_invite_created and admin.signup_invite_revoked; changes
need a sign-in within the last five minutes. The command line
equivalents are opdns-cp admin signup-mode get|set and opdns-cp admin invite new|list|revoke, which take the same code paths.
Dashboard error reports
Section titled “Dashboard error reports”Uncaught dashboard errors reported by browsers (scrubbed of names,
addresses, emails and ids before sending) are kept 30 days. There is no
page for them yet; list them with GET /v1/admin/client-errors on the
admin API (paginated, newest first).
Role admin endpoints
Section titled “Role admin endpoints”Every opdns-cp role serves /metrics, /healthz, /readyz and
/livez on its admin port (--admin-addr, default :9090). Two roles add
routes that act:
| Role | Route | Does |
|---|---|---|
certs |
POST /admin/rotate |
start a forced certificate rotation on the leader; waits up to ?wait= (default 45 s, at most 55 s): 200 done, 202 still running, 500 failed, 409 not the leader, 503 busy |
certs |
GET /admin/rotate |
the last rotation since the instance started (404 when none) |
listc |
POST /admin/build |
run a list build cycle now; waits up to ?wait= (default 50 s, at most 55 s): 200 done, 500 failed, 202 still running, 409 another on-demand build running, 503 the compiler not running |
listc |
GET /admin/build |
the last on-demand build (404 when none) |
listc |
GET /admin/rollout, POST /admin/rollback, POST and DELETE /admin/pin |
list rollouts |
These routes are guarded the same way everywhere: with OPDNS_ADMIN_TOKEN
set on the role, a request needs Authorization: Bearer <token> (401
otherwise); without it, only loopback clients are served (403 otherwise).
Outside env=dev, every role refuses to start with a published
development secret: the development admin token or S3 secret, or a
secrets keyring holding the development key (or any key named dev).
curl -X POST -H "Authorization: Bearer $OPDNS_ADMIN_TOKEN" \ "http://127.0.0.1:9090/admin/build?wait=30s"opdns-cp certs --once --force, run while another instance leads, asks
that leader to rotate through POST /admin/rotate
(--leader-admin-url, default http://127.0.0.1:<admin-addr port>, with
OPDNS_ADMIN_TOKEN) and follows the rotation. Sending the leader
SIGUSR1 also rotates.