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 (e.g., update ipset, download files).
  • Flow plugins control execution (e.g., 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 (e.g., 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 — 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.