OxiDNS is a programmable, policy-orchestration DNS engine written in Rust, aimed at operators of soft routers, OpenWrt boxes, homelabs and advanced self-hosted networks who need explainable, configurable query routing.

What it is

OxiDNS is a plugin-based DNS engine built in Rust for complex networks, combining declarative policy with a WebUI, management API, query records, Prometheus metrics and live logs. It lives in the DNS/networking infrastructure space and takes direct inspiration from mosdns, but positions itself as more than rule-based split routing: it places DNS requests, upstream responses and network side effects on a single composable, explainable policy pipeline.

The concrete problem it addresses is that complex DNS behaviour usually becomes hard to configure, validate and trace once it grows past simple domain split rules. OxiDNS addresses this with sequence, which combines matchers, executors and providers into reusable conditional branches, jumps and fallback chains, while query audit records, execution paths, structured logs and metrics let you answer what matched, what ran and why a result was chosen. The core path stays simple: client → server → sequence (matcher + executor + provider) → upstream or local answer → response, with side effects branching off.

Key capabilities

• Serve UDP, TCP, DoT, DoQ and DoH (HTTP/1.1, HTTP/2, HTTP/3) through one policy, with multi-protocol upstreams, concurrent response adjudication, connection reuse, bootstrap, SOCKS5 and a unified network.outbound.
• Orchestrate policy with sequence: conditional matching, executor composition, jumps and fallback chains assembled from tag-combined plugins (domain_set, forward, udp_server).
• Process responses with TTL-aware cache and negative cache, ECS and ECS client-address mapping, local records, redirects, response construction, and dual-stack/IP preference.
• Load rule data from domain and IP sets, GeoIP, GeoSite, AdGuard rules and dynamic domain learning.
• Drive network behaviour from DNS results: Linux ipset / nftset, RouterOS address-list and static route, HTTP webhooks and external scripts.
• Observe and operate it with query audit and execution paths, real-time logs, Prometheus metrics, upstream probing, health checks, config validation and hot reload, matcher result pinning and targeted provider reload.
• Deploy through multi-platform builds, Debian packages, an OpenWrt LuCI plugin (luci-app-oxidns), a built-in WebUI and management API, and service-based installation.

Who uses it and how

• Home gateways, side routers, OpenWrt devices, NAS boxes and homelabs that run DNS long-term with fine-grained control.
• Operators routing policy by domain, client, query type or response result, with multi-upstream concurrency and primary/backup fallback.
• Environments needing encrypted DNS with a custom egress path via SOCKS5 or network.outbound.
• People doing ad blocking, local overrides, dual-stack preference, ECS and dynamic rule learning.
• Setups where DNS results drive firewall sets, address lists or policy routing through ipset/nftset or RouterOS.

Getting started

The README offers a one-line install that downloads the platform release, installs the WebUI and registers and starts a system service: curl -fsSL https://oxidns.org/install.sh | sudo sh, with irm https://oxidns.org/install.ps1 | iex for administrator PowerShell; Debian packages, Docker, portable installs and the OpenWrt route via luci-app-oxidns are documented under installation, and config changes should be validated with oxidns check.

How it compares

The project is GPL-3.0 licensed and self-hostable, with all policy configuration, query records and metrics kept on your own infrastructure, and it can be custom-compiled to trim protocols and plugins. Among the tools it names, it sits alongside mosdns as an inspiration, but differs by putting requests, upstream responses and network side effects on one composable pipeline rather than focusing only on rule-based split routing.

When to use it — and when not

You must be willing to learn the configuration model: providers, matchers, executors and servers are combined by tag, and after changing config you need to run oxidns check before applying it — it is explicitly not a one-click ad blocker nor an authoritative DNS service. It is also not for someone who wants to operate nothing; while the install script registers a system service and the project ships a WebUI, Debian package and OpenWrt plugin, exposing the management API requires enabling api.http.auth and constraining sources with a firewall or reverse proxy yourself. Note the project carries the GPL-3.0 licence, 15 open issues, and the README points to external documentation at oxidns.org for configuration, scenarios and benchmarks rather than carrying them inline.

client -> server -> sequence (matcher + executor + provider)
                         |-> upstream / local answer -> response
                         `-> side effects

plugins:
  - tag: internal_domains
    type: domain_set
    args:
      exps: ["domain:corp.lan"]

  - tag: forward_internal
    type: forward
    args:
      upstreams:
        - addr: "udp://192.168.1.1:53"

  - tag: forward_public
    type: forward
    args:
      upstreams:
        - addr: "tls://dns.quad9.net:853"
          bootstrap: "9.9.9.9:53"

  - tag: main
    type: sequence
    args:
      - matches: "qname $internal_domains"
        exec: "$forward_internal"
      - matches: "!has_resp"
        exec: "$forward_public"
      - exec: accept

  - tag: dns_server
    type: udp_server
    args:
      entry: main
      listen: ":5335"

curl -fsSL https://oxidns.org/install.sh | sudo sh

irm https://oxidns.org/install.ps1 | iex

curl -fsS http://127.0.0.1:9199/api/health
dig @127.0.0.1 example.com
dig @127.0.0.1 example.com +tcp