Skip to content
Log inDashboard

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.

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.

  1. 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:5353 with a generated configuration):

    Terminal window
    sudo apt install unbound
    sudo systemctl disable --now unbound

    The node looks for unbound on the PATH and in /usr/sbin, /usr/local/sbin, /opt/homebrew/sbin and /sbin; set unbound.binary otherwise. 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.

  2. Download and verify the binary:

    Terminal window
    V=<version>; A=linux_arm64
    curl -fLO https://github.com/operomtl/opdns/releases/download/v$V/opdns-node_v${V}_$A
    curl -fLO https://github.com/operomtl/opdns/releases/download/v$V/SHA256SUMS
    sha256sum --ignore-missing -c SHA256SUMS
    sudo install -m 0755 opdns-node_v${V}_$A /usr/local/bin/opdns-node
  3. Create the opdns user and its data directory, and install the unit:

    Terminal window
    sudo useradd --system --user-group --home-dir /var/lib/opdns --shell /usr/sbin/nologin opdns
    sudo install -d -o opdns -g opdns -m 0700 /var/lib/opdns

    Save the unit file as opdns-node.service in the current directory, then:

    Terminal window
    sudo install -m 0644 opdns-node.service /etc/systemd/system/opdns-node.service
    sudo systemctl daemon-reload
  4. 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.d
    printf '[Resolve]\nDNSStubListener=no\n' | sudo tee /etc/systemd/resolved.conf.d/opdns.conf
    sudo systemctl restart systemd-resolved
    sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
  5. 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.

  6. Start it and check:

    Terminal window
    sudo systemctl enable --now opdns-node
    opdns-node status
    journalctl -u opdns-node -f

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

/etc/systemd/system/opdns-node.service
# 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 node
Documentation=https://opdns.io/docs/self-hosted/install-binary/
Wants=network-online.target
After=network-online.target
# Port 53 must be free: disable systemd-resolved's stub listener first
# (DNSStubListener=no).
Conflicts=dnsmasq.service
[Service]
Type=exec
User=opdns
Group=opdns
DynamicUser=no
EnvironmentFile=-/etc/opdns/node.env
Environment=OPDNS_DATA_DIR=/var/lib/opdns
ExecStart=/usr/local/bin/opdns-node run
ExecReload=kill -HUP $MAINPID
Restart=on-failure
RestartSec=5s
RestartPreventExitStatus=2
TimeoutStopSec=20s
LimitNOFILE=65536
UMask=0077
StateDirectory=opdns
StateDirectoryMode=0700
ConfigurationDirectory=opdns
ReadWritePaths=/var/lib/opdns
# Bind port 53 (and 853/443) as an unprivileged user, and nothing else.
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
PrivateDevices=yes
ProtectHostname=yes
ProtectClock=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectControlGroups=yes
ProtectProc=invisible
ProcSubset=pid
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
RestrictNamespaces=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
LockPersonality=yes
MemoryDenyWriteExecute=yes
RemoveIPC=yes
SystemCallArchitectures=native
SystemCallFilter=@system-service
SystemCallFilter=~@privileged
SystemCallErrorNumber=EPERM
[Install]
WantedBy=multi-user.target

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

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.

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.

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

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 reference
opdns-node backup [--config FILE] [--data-dir DIR] ARCHIVE
opdns-node restore [--force] [--config FILE] [--data-dir DIR] ARCHIVE
opdns-node import-export [--profile ID] [--profile-file FILE] [--config FILE] EXPORT.zip
opdns-node hash-password
opdns-node version

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