Skip to content
Log inDashboard

Admin tools

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.

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.

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.

Terminal window
opdns-cp admin profile list --email [email protected]
opdns-cp admin profile get abc123 --document
opdns-cp admin profile set abc123 settings.block_mode=refused --reason "ticket 812" --yes
opdns-cp admin profile create --email [email protected] --name Home --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.

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.
Terminal window
opdns-cp admin profile suspend abc123 --reason "abuse ticket 812" \
--public-reason "terms of service violation, contact support" --yes
opdns-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.

The operator blocks of the admin app can also be managed without the API:

Terminal window
opdns-cp admin operator block list
opdns-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 --yes
opdns-cp admin operator block remove <id> --yes
opdns-cp admin operator block report --from 2026-07-01 --to 2026-09-30 --csv
opdns-cp admin operator source-block list
opdns-cp admin operator source-block add --cidr 192.0.2.0/24 --reason "ABUSE-31 flood" \
--action drop --expires-in 24h --yes
opdns-cp admin operator source-block remove <id> --yes

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

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.

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.

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.

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

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. e focuses the message; Ctrl+Enter previews.
  • Internal notes: only staff see them; they cannot be edited or removed. n focuses 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.

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

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

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

Terminal window
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.