DOCSEARCHbyAlgolia
Submit Docs

OxiDNS Documentation

website·Indexed 29 days ago

https://oxidns.org

Documentation for OxiDNS, a DNS server featuring a plugin-based architecture with matchers, executors, and providers. Includes guides on installation (including OpenWrt/LuCI), configuration via YAML, API references for Prometheus metrics and configuration checks, and migration workflows from mosdns.

Tokens
120.3K
Snippets
471
Records
821
Agent score
47%

What's inside OxiDNS

  1. Overview of OxiDNS Executors

    Executors are the core action layer in OxiDNS. They are responsible for operational tasks including reading or writing requests, setting responses, querying upstreams, caching results, implementing fallback logic, emitting logs, and triggering system integrations. When implementing or configuring executors, consider whether the plugin acts only during the forward stage or if it can rewrite results on the return path, and whether it is part of the main resolution path or serves as an observability/side-effect plugin.

  2. Understand the Plugin Extension API routing format

    Plugins register management and observation interfaces using a unified tag-based routing format. The availability of a route depends on the current configuration and binary compilation capabilities. The general format is /api/plugins/<plugin_tag>/<route>. Some plugins may bind primary resources to prefix routes, such as query_recorder using /api/plugins/<tag>/records/<id>.

  3. Understand OxiDNS Provider fundamentals

    Providers in OxiDNS convert rule sets from one-off literals into reusable data assets to reduce duplication and centralize shared datasets. Providers with domain or IP match capabilities can be referenced by matchers using "$tag" or composed via domain_set or ip_set. Composite providers compile local rules and consult referenced providers at runtime rather than merging all data into a single matcher.

    OxiDNS uses lazy initialization: providers are only initialized at startup if they are referenced by a server, executor, or matcher. Unused providers are skipped, omitted from the runtime registry, and trigger a warning log.

  4. Understand OxiDNS documentation versioning

    The default documentation at oxidns.org follows the main branch of the OxiDNS repository (marked as current / Next in Docusaurus). It describes the current mainline capabilities and may include features, plugins, or fields not yet present in a specific stable release. Because the site does not maintain frozen snapshots for every release, users needing documentation for a historical version should switch to the corresponding Git tag and refer to the README.md, docs/, config.yaml, and release notes within the repository.

  5. Configure the forward executor for DNS upstreaming

    The forward executor initiates DNS queries to upstream resolvers. It supports single-upstream mode (direct query) and multi-upstream mode (concurrent queries where the first successful response wins). If short_circuit is enabled, the executor chain stops immediately upon receiving a valid response.
    # Single upstream
- exec: "forward 1.1.1.1"
# Concurrent upstreams
- exec: "forward 1.1.1.1 8.8.8.8"
# Single upstream with short circuit
- exec: "forward 1.1.1.1 short_circuit=true"

  6. Third-party Plugin Ecosystem Strategy

    Oxidns is exploring two paths for third-party plugins:

    • WebAssembly (Wasm): For independent distribution using stable interfaces and sandbox isolation.
    • Native Dynamic Libraries: For scenarios requiring extremely low latency and high throughput. Before opening a third-party ABI, the project will prioritize stabilizing the configuration model, lifecycle, capability declarations, resource limits, and fault isolation semantics.

  7. OxiDNS Architectural Overview

    OxiDNS is a DNS policy orchestration engine designed to decouple protocols from policies. It separates the system into a Control Plane (responsible for YAML configuration, schema validation, plugin dependency graphs, and management APIs) and a Data Plane (responsible for processing DNS requests). The core data path follows this flow: server -> DnsContext -> compiled sequence -> matcher / executor / provider -> response or side effects.

  8. Understand OxiDNS documentation versioning

    The documentation at oxidns.org tracks the main branch of the OxiDNS repository (labeled current / Next). Because it describes mainline capabilities, it may include features, plugins, or fields not yet available in your installed release. To find documentation for a specific historical release, switch to the corresponding Git tag and refer to the README.md, docs/, config.yaml, and release notes within that tag.

  9. Understand the OxiDNS plugin architecture

    OxiDNS capabilities are implemented as plugins organized into four functional layers. Complex policies are created by composing these layers in a pipeline: server -> sequence -> matcher -> executor -> provider -> upstream/side effect.

    The layers are:

    • server: Handles network ingress, listening for traffic and handing it to the policy entrypoint.
    • executor: Performs actions such as forwarding, caching, rewriting, observability, and system integrations.
    • matcher: Evaluates branch conditions for the sequence executor.
    • provider: Supplies reusable domain or IP datasets consumed by matchers and executors.

  10. Understand and use Providers for reusable rule sets

    Providers in Oxidns transform individual rules into reusable data assets. They are used to reduce repetitive configurations and centralize shared rules.

    Key behaviors include:

    • Referencing: Providers can be referenced directly by a matcher using "$tag" or combined via domain_set / ip_set.
    • Efficiency: domain_set and ip_set compile only their local rules and query the referenced provider at runtime rather than creating rule copies.
    • Lazy Loading: Only providers that are directly or indirectly consumed by a server, executor, or matcher are initialized at startup. Unused providers are skipped and trigger a warning log.
    • Dynamic Reloading: Every active provider registers a management interface at POST /api/plugins/<provider_tag>/reload. This allows refreshing data snapshots without rebuilding other plugins. This can be triggered via the reload_provider executor or the WebUI.

  11. OxiDNS Global Configuration Overview

    OxiDNS uses a YAML configuration file divided into six primary top-level sections:

    • runtime: Runtime parameters.
    • api: Management API settings.
    • log: Log output configuration.
    • network: Shared network outbound configurations (used for HTTP downloads, upgrade checks, and webhooks).
    • include: Loading plugin definitions from external files.
    • plugins: Definitions for all plugin instances that compose the DNS workflow.
    runtime:
  worker_threads: 4

api:
  http: "127.0.0.1:9088"

log:
  level: info
  file: ./oxidns.log

network:
  outbound:
    default: direct
    profiles:
      direct:
        resolver: system
        proxy: none

include: []

plugins:
  - tag: seq_main
    type: sequence
    args:
      - exec: "forward 1.1.1.1"

  12. Report a high-quality bug in OxiDNS

    To ensure a bug report is actionable, include the following details:

    • OxiDNS version, bundle, and commit (if applicable).
    • Operating system, CPU architecture, and installation method.
    • A redacted minimal configuration and the actual -d/--working-dir used.
    • Steps to reproduce the query, startup, or reload issue.
    • Expected vs. observed behavior.
    • The first causal error encountered and any diagnostics already performed.