Skip to content

05_PLUGINS_USERGUIDE.md

Latest commit

 

History

History
102 lines (89 loc) · 4.81 KB

05_PLUGINS_USERGUIDE.md

File metadata and controls

102 lines (89 loc) · 4.81 KB
Raw

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.