lazydns

Plugins Guide (User)

Plugin System Overview

Explain plugin execution flow, priorities, and common plugin types:

• query plugins (manipulate DNS queries/responses)
• exec plugins (side-effecting tasks)
• flow plugins (control flow)

Key concepts

• Plugin types:
  • Query plugins operate on request/response path and may return a DNS response.
  • Exec plugins perform side-effecting actions (such as update ipset, download files).
  • Flow plugins control execution (such as jump/goto/return semantics).
• Plugin factory / builder: registration mechanism that allows plugins to be discovered and built from configuration.
• Datasets: text-based domain and IP lists used by dataset plugins; support for auto-reload and merging of files/inline expressions.

Example plugin sequence (ASCII)

This sequence shows a typical plugin chain where hosts provides immediate answers, cache handles cached responses, and forward sends queries to upstream resolvers when needed.

Client
  |
  v
 [Listener]
  |
  v
[Request Handler]
  |
  v
+--------------------------+
| Plugin: hosts            |  => If match -> Respond (short-circuit)
+--------------------------+
  |
  v
+--------------------------+
| Plugin: cache            |  => If cached -> Respond
+--------------------------+
  |
  v
+--------------------------+
| Plugin: forward          |  => Query upstream and return response
+--------------------------+
  |
  v
 Response -> Client

This pipeline is intentionally simple: listeners hand requests to a single handler which executes an ordered set of plugins. Plugins may short-circuit the pipeline by producing a response (such as hosts or cache) or let the request continue to upstreams.

Built-in Plugins

Short pages or subsections for major plugins with purpose & example config:

• forward: forward queries to upstreams
• cache: hierarchical cache with TTL handling and LazyCache
• hosts: static hosts mapping
• acl: allow/deny by client IP
• geoip: IP-based country tagging (GeoIP)
• geosite: domain category tagging (GeoSite)
• cron: scheduled background jobs (HTTP, command, invoke-plugin)
• dataset.*: domain/ip sets
  • domain_set: domain matching dataset (full/domain/regexp/keyword)
  • ip_set: extract A/AAAA addresses and materialize ipset entries
• sequence: Sequence plugin, a rule-based executor to compose plugins into chains
• executable.*: exec-style plugins (downloader, ipset, nftset)
  • arbitrary: return predefined DNS records for matching queries
  • blackhole: return configured A/AAAA answers (sinkhole aliases)
  • collector: simple in-process query counter; optional Prometheus collector when built with metrics feature
  • debug_print: log queries/responses for debugging
  • downloader: download remote files and atomically update local files
  • drop_resp: clear any existing response in the execution context
  • dual_selector: filter answers by IPv4/IPv6 preference
  • ecs: prepare EDNS0 Client Subnet options (ECS)
  • edns0opt: add arbitrary EDNS0 options for upstream queries
  • fallback: try child plugins in order with automatic failover
  • ipset (exec): materialize A/AAAA answers into ipset entries
  • mark: set lightweight metadata marks on the request
  • nftset: materialize A/AAAA answers into nftables sets
  • query_summary: build and store a concise request summary
  • rate_limit: per-client rate limiting
  • redirect: rewrite query names (supports wildcards)
  • reverse_lookup: cache A/AAAA -> name mappings and answer PTR
  • ros_addrlist: RouterOS address list helper and notifier
  • sleep: pause execution for a duration
  • ttl: fix or clamp TTL values on responses

Example plugin configuration

plugins:
  - tag: cache
    type: cache
    config:
      min_ttl: 30

Ordering & Priority

How priorities and plugin lists affect execution.

---

TODO: Link each built-in plugin to deeper docs pages.

This site is open source. Improve this page.