Install the static binary
Each release carries static
binaries named opdns-node_<version>_<os>_<arch> for linux_amd64,
linux_arm64 and darwin_arm64, with a SHA256SUMS file. The binary has no dependencies
except Unbound, which it starts and supervises; it refuses to start without
one.
Install on Linux with systemd
Section titled “Install on Linux with systemd”For Debian, Ubuntu and Raspberry Pi OS, on amd64 or arm64. The node
runs as a dedicated opdns user from the systemd unit in
The unit file below.
-
Install Unbound, and stop the distribution’s own Unbound service, which would take port 53 (the node runs its own instance on
127.0.0.1:5353with a generated configuration):Terminal window sudo apt install unboundsudo systemctl disable --now unboundTerminal window sudo apk add unboundAlpine has no systemd: run the node from your init system with the same user and data directory.
The node looks for
unboundon thePATHand in/usr/sbin,/usr/local/sbin,/opt/homebrew/sbinand/sbin; setunbound.binaryotherwise. It needs Unbound 1.17.0 or newer and refuses to start with an older one, naming the version it found: Debian 12 and Raspberry Pi OS 12 ship 1.17.1, Ubuntu 24.04 1.19, and current Alpine releases newer ones. -
Download and verify the binary:
Terminal window V=<version>; A=linux_arm64curl -fLO https://github.com/operomtl/opdns/releases/download/v$V/opdns-node_v${V}_$Acurl -fLO https://github.com/operomtl/opdns/releases/download/v$V/SHA256SUMSsha256sum --ignore-missing -c SHA256SUMSsudo install -m 0755 opdns-node_v${V}_$A /usr/local/bin/opdns-node -
Create the
opdnsuser and its data directory, and install the unit:Terminal window sudo useradd --system --user-group --home-dir /var/lib/opdns --shell /usr/sbin/nologin opdnssudo install -d -o opdns -g opdns -m 0700 /var/lib/opdnsSave the unit file as
opdns-node.servicein the current directory, then:Terminal window sudo install -m 0644 opdns-node.service /etc/systemd/system/opdns-node.servicesudo systemctl daemon-reload -
Free port 53 from systemd-resolved’s stub listener. The host keeps resolving through systemd-resolved’s upstreams:
Terminal window sudo mkdir -p /etc/systemd/resolved.conf.dprintf '[Resolve]\nDNSStubListener=no\n' | sudo tee /etc/systemd/resolved.conf.d/opdns.confsudo systemctl restart systemd-resolvedsudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf -
Enrol. In the dashboard open Nodes → Add node, create a code, then:
Terminal window sudo -u opdns opdns-node enrol --token <enrolment-code>Or put
OPDNS_ENROL_TOKEN=<enrolment-code>in/etc/opdns/node.env(mode 0600): the node enrols on its first start and ignores the variable afterwards. See Enrol a node, or standalone mode to run without an account. -
Start it and check:
Terminal window sudo systemctl enable --now opdns-nodeopdns-node statusjournalctl -u opdns-node -fThe status page is on port 8053.
No configuration file is needed for an enrolled node: the list signing key
comes from the cloud (list signing keys).
Settings go in /etc/opdns/node.yaml, or as OPDNS_<SECTION>_<KEY>
variables in /etc/opdns/node.env. A command-line flag wins over the
environment, which wins over the file. Every key is on the
configuration reference.
The unit file
Section titled “The unit file”# opdns-node: the self-hosted opdns node as a hardened systemd service.## binary /usr/local/bin/opdns-node (static; runs the distribution's unbound)# config /etc/opdns/node.yaml (optional), /etc/opdns/node.env (optional,# OPDNS_* variables such as OPDNS_ENROL_TOKEN)# data /var/lib/opdns (owned by the opdns user)# user opdns, the same name as in the container image; the ids# `useradd --system` picks here do not matter## Exit status 2 means "not set up yet" or "invalid configuration": the unit# does not restart on it; enrol the node (or fix the config) and start it.[Unit]Description=opdns self-hosted DNS nodeDocumentation=https://opdns.io/docs/self-hosted/install-binary/Wants=network-online.targetAfter=network-online.target# Port 53 must be free: disable systemd-resolved's stub listener first# (DNSStubListener=no).Conflicts=dnsmasq.service
[Service]Type=execUser=opdnsGroup=opdnsDynamicUser=noEnvironmentFile=-/etc/opdns/node.envEnvironment=OPDNS_DATA_DIR=/var/lib/opdnsExecStart=/usr/local/bin/opdns-node runExecReload=kill -HUP $MAINPIDRestart=on-failureRestartSec=5sRestartPreventExitStatus=2TimeoutStopSec=20sLimitNOFILE=65536UMask=0077
StateDirectory=opdnsStateDirectoryMode=0700ConfigurationDirectory=opdnsReadWritePaths=/var/lib/opdns
# Bind port 53 (and 853/443) as an unprivileged user, and nothing else.AmbientCapabilities=CAP_NET_BIND_SERVICECapabilityBoundingSet=CAP_NET_BIND_SERVICENoNewPrivileges=yes
ProtectSystem=strictProtectHome=yesPrivateTmp=yesPrivateDevices=yesProtectHostname=yesProtectClock=yesProtectKernelTunables=yesProtectKernelModules=yesProtectKernelLogs=yesProtectControlGroups=yesProtectProc=invisibleProcSubset=pidRestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINKRestrictNamespaces=yesRestrictRealtime=yesRestrictSUIDSGID=yesLockPersonality=yesMemoryDenyWriteExecute=yesRemoveIPC=yesSystemCallArchitectures=nativeSystemCallFilter=@system-serviceSystemCallFilter=~@privilegedSystemCallErrorNumber=EPERM
[Install]WantedBy=multi-user.targetThe unit has Conflicts=dnsmasq.service: starting the node stops dnsmasq,
which would otherwise hold port 53. If you need dnsmasq for DHCP, remove
that line and set port=0 in dnsmasq’s configuration instead.
What the unit does
Section titled “What the unit does”| Runs as | the opdns user, with only CAP_NET_BIND_SERVICE (ports 53, 443, 853), no new privileges |
| Files | reads /etc/opdns/node.yaml and /etc/opdns/node.env if they exist; writes only /var/lib/opdns (ProtectSystem=strict, private /tmp, no home directories) |
| Restarts | on failure after 5 seconds, except on exit status 2 |
systemctl reload opdns-node |
sends SIGHUP: applies the reloadable keys of the configuration, pulls the profile and lists again and reloads the TLS certificate |
| Stops | on SIGTERM, within 20 seconds: drains listeners, flushes pending log records, closes the link, stops Unbound |
The unit’s systemd-analyze security exposure level is 1.7 (“OK”)
with systemd 252 on Debian 12. Check it on your host with
systemd-analyze security --offline=yes /etc/systemd/system/opdns-node.service
(systemd 252 or newer; older versions check the loaded unit with
systemd-analyze security opdns-node). What stays open is what a DNS
server needs: the host network, Internet and local sockets (Unix sockets
for Unbound’s control, netlink for the IPv6 route check), and the
capability to bind port 53.
Exit status 2 means the node is not set up (no identity, no enrolment code and no standalone profile) or its configuration is invalid. It prints what to do, and systemd does not restart it: fix the cause and start it. A node never serves unfiltered DNS because it was not set up.
Certificates for encrypted DNS
Section titled “Certificates for encrypted DNS”With listen.dot, listen.doh, listen.doq or listen.doh3 set, the
node needs listen.tls_cert and listen.tls_key. It checks both files
every second and loads a renewed pair as soon as it appears, with no
restart; a pair that fails to load is logged and the previous certificate
stays. So a renewal hook only has to write the files where the opdns user
can read them (for example under /etc/opdns). systemctl reload opdns-node forces a reload. See also
Encrypted DNS on the node.
macOS and other systems
Section titled “macOS and other systems”On macOS, brew install unbound, then run opdns-node run from a
terminal or your own launchd job. There is no packaged service yet. The
node needs to bind port 53, so run it as root or on another port
(listen.udp, listen.tcp).
Commands
Section titled “Commands”opdns-node run [--config FILE] [--data-dir DIR] [--log-level L] [--enrol-token CODE] [--profile-file FILE] [--lists-url URL] [--print-config]opdns-node enrol --token CODE|TOKEN [--node-id ID] [--replace] [--keep-cloud-profile] [--yes] [--config FILE] [--data-dir DIR]opdns-node unenrol [--purge-logs] [--local-only] [--config FILE] [--data-dir DIR]opdns-node rotate-token [--config FILE] [--data-dir DIR]opdns-node status [--config FILE] [--addr HOST:PORT] [--json]opdns-node config check [--config FILE | FILE]opdns-node config referenceopdns-node backup [--config FILE] [--data-dir DIR] ARCHIVEopdns-node restore [--force] [--config FILE] [--data-dir DIR] ARCHIVEopdns-node import-export [--profile ID] [--profile-file FILE] [--config FILE] EXPORT.zipopdns-node hash-passwordopdns-node versionrun is the default. enrol, unenrol and rotate-token are on
Enrol a node, config check and
config reference on Configuration,
backup and restore on
Upgrade and back up,
import-export on
Standalone mode,
hash-password on Network access.
status asks the running node’s status page, or reads the data directory
if the node is not running (exit status 3).