Standalone mode
A standalone node has no account and no link. Its profile lives in its config file; it downloads the same public list artifact as everyone else.
Start in one command
Section titled “Start in one command”An empty data volume and OPDNS_MODE=standalone are all it needs:
docker run -d --name opdns-node --restart unless-stopped --read-only \ -p 53:53/udp -p 53:53/tcp \ -p 127.0.0.1:8053:8053 \ -v opdns-node:/var/lib/opdns \ -e OPDNS_MODE=standalone \ ghcr.io/operomtl/opdns-node:<version>On its first run the node writes a starter profile to
/var/lib/opdns/profile.yaml (below), fetches the public lists and filters
from then on. The local page (http://127.0.0.1:8053/) shows the
local API token once. The same works
without Docker: mode: standalone in the config and opdns-node run.
Configure
Section titled “Configure”mode: standalone
lists: url: https://lists.opdns.net/lists/public/latest.json # the default; none: no lists poll: 6h
profile: id: home01 # any 6 characters, [a-z0-9] version: 1 # bump when you change the profile name: Home lists: [1, 10] # list ids from the catalogue (GET /v1/lists) deny: - pattern: "*.ads.example" allow: - pattern: "=cdn.example.net" rewrites: - {name: nas.home.arpa, type: A, value: 192.168.1.2} security: {threat_intel: true, nrd: true} parental: {safe_search: false} settings: block_mode: nxdomain logs_enabled: true log_client_ip: true log_domains: true retention_days: 30 cname_uncloak: true linked_ips: []mode: standalone alone is enough to start: with neither profile: nor
profile_file:, the node writes a starter profile to
<data_dir>/profile.yaml on its first run (the cloud’s defaults for a new
profile: security protections on, no list subscribed, logs kept on the node
for 30 days), uses it as its profile file and logs where it is. Edit it, or
write it through the local API; it is never overwritten.
Without lists.url the node fetches the public lists (see below); with
lists.url: none it filters with the profile’s own rules only.
The profile block uses the same field names as the profile document the
cloud publishes (see the ProfileDocument schema in the
API reference); unknown fields are errors. Instead
of an inline profile:, you can point profile_file: (or --profile-file)
at a JSON or YAML file with the same content.
Without lists.url, a standalone node polls the public list artifact
that opdns publishes for standalone nodes,
https://lists.opdns.net/lists/public/latest.json, every lists.poll
(6 hours by default). No account is needed. The endpoint limits each client
network (an IPv4 /24 or an IPv6 /48). Over the limit it answers
429 Too Many Requests with Retry-After, and the node waits at least
that long before it tries again. Set lists.url: none to fetch no lists
and filter with the profile’s own rules only.
lists.url can also name another artifact (…/v<N>.bin) or the
latest.json pointer next to it, such as your own mirror. The node follows
the pointer to the newest artifact on every poll. The artifact must verify with a trusted Ed25519 key. By default
(lists.trust_cloud_key: true) the node trusts the pubkey published in
that latest.json, fetched over HTTPS from the same place, and keeps it in
lists_keys.json for offline restarts; on a key rotation the old key stays
trusted until the next fetch confirms the new one. To pin the key yourself,
set lists.public_keys and lists.trust_cloud_key: false.
Instead of writing the profile by hand, you can use the profile.json of
any profile from an account export:
it is the same format.
List ids come from the public catalogue:
GET /v1/lists needs no
account.
Check the result without starting the node:
opdns-node config check /etc/opdns/node.yamlIt validates the file (unknown keys are errors, including in the profile) and prints the effective configuration with the source of every value (Configuration).
Edit the profile file
Section titled “Edit the profile file”With profile_file, the node watches the file and applies an edit within
about two seconds, with no restart and no signal. It polls the file’s
modification time, size and inode, so it also sees an editor that writes a
new file and renames it over the old one, on bind mounts and network
shares too. An edit that does not parse or validate changes nothing: the
node keeps the last good profile and shows the error, with its line and
field, on the local page.
An inline profile: in node.yaml is read at start only; change it and
restart the node, or move it to a profile_file.
Start from a cloud profile
Section titled “Start from a cloud profile”The data export of an
opdns account holds each profile as profiles/<id>/profile.json, in the
format the node reads. To run a cloud profile on a standalone node:
opdns-node import-export opdns-export.zip --profile abc123It takes the profile from the archive (--profile can be left out when
the archive holds one), checks that it parses and compiles, and writes it
to profile_file (or --profile-file), mode 0600 since it lists your
linked addresses. A running node picks it up like any edit.
What is different from enrolled mode
Section titled “What is different from enrolled mode”- No dashboard: logs stay in the node’s SQLite file; read them with
sqlite3. The local API does not serve logs yet. - The node re-fetches the list artifact every
lists.poll(default 6 hours, give or take 10 % so nodes do not all ask at once), with a conditional request. When the download endpoint answers 429 or 503 the node keeps its current lists and waits at least theRetry-Afterit sent before trying again. - opdns sees only the artifact downloads (address and time).
Local page
Section titled “Local page”http://<node>:8053/ shows health, versions, the loaded profile and lists,
the config file path, the SQLite size, and the
network guard. /api/status is the
same as JSON, /healthz is the health check, and /metrics serves
Prometheus metrics (on by default;
Metrics). A
password can
protect the page.
They answer only devices on your network; see
Network access.
Local API
Section titled “Local API”A standalone node has a small REST API on the same port, for scripts and home automation:
| Request | Does |
|---|---|
GET /api/profile |
the profile in use, with its version as ETag |
PUT /api/profile |
replace the profile (JSON or YAML, the same format as the file); the node validates it, rewrites the profile file (as JSON) and applies it at once, and answers with the stored profile and its new version |
GET /api/lists |
the loaded list artifact: version, entries, when it was built and fetched, its source, the last error, and every list with its category and whether the profile applies it |
POST /api/lists/refresh |
fetch the list artifact now instead of at the next lists.poll (202) |
Every request needs Authorization: Bearer <token>. Set the token with
web.api_token (at least 16 characters), or leave it empty: the node then
generates one (opdnslocal_…) on its first run, keeps it in
<data_dir>/secrets/api_token, and shows it once on the local page.
TOKEN=$(sudo cat /var/lib/opdns/secrets/api_token)curl -H "Authorization: Bearer $TOKEN" http://192.168.1.2:8053/api/profileWrites are guarded against lost updates: send the ETag of your
GET back as If-Match (or leave the version you read in the body). If
the profile changed in between, by another write or by hand in the file,
the answer is 409 version_mismatch and nothing changes. A profile the
node refuses is 422 validation_failed with the reason.
The API writes only a profile in its own file: with the profile inline in
node.yaml, PUT /api/profile answers 409 and asks you to move it to a
file named by profile_file. An enrolled node answers 404 on every
/api/profile and /api/lists route: it is configured from the dashboard.