filter

README

filter

Description

The filter plugins enables blocking requests based on predefined lists and rules, creating a DNS sinkhole similar to Pi-Hole or AdGuard.

Features

• Regex and simple string matching support.
• Inspection of CNAME, SVCB and HTTPS records detects and blocks cloaking.
• Block replies are fully cacheable by the cache plugin.

Syntax

filter {
    allow FILE
    block FILE
    uncloak
    ttl DURATION
}

• allow load FILE to the whitelist.
• block load FILE to the blacklist.
• uncloak enables response uncloaking, disabled by default.
• ttl sets TTL for blocked responses, default is 3600s.

Metrics

If monitoring is enabled (via the prometheus plugin) then the following metric are exported:

• coredns_filter_blocked_requests_total{server} - count per server

Examples

.:53 {
    filter {
        allow /lists/allowlist.txt
        block /lists/denylist.txt
        uncloak
        ttl 600
    }
    forward . tls://1.1.1.1 tls://1.0.0.1 {
        tls_servername cloudflare-dns.com
    }
}

Documentation

Index

• Variables
• type Filter
  • func New() *Filter
  • func (f *Filter) Load() error
  • func (f *Filter) Match(name string) bool
  • func (f *Filter) Name() string
  • func (f *Filter) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
• type PatternMatcher
  • func NewPatternMatcher() *PatternMatcher
  • func (f *PatternMatcher) Add(pattern string) error
  • func (f *PatternMatcher) Load(r io.Reader) error
  • func (f *PatternMatcher) Match(qname string) bool
• type ResponseWriter
  • func (w *ResponseWriter) WriteMsg(m *dns.Msg) error

Variables

var (
	BlockCount = promauto.NewCounterVec(prometheus.CounterOpts{
		Namespace: plugin.Namespace,
		Subsystem: pluginName,
		Name:      "blocked_requests_total",
		Help:      "Counter of blocked requests.",
	}, []string{"server"})
)

Types

type Filter

type Filter struct {
	Next plugin.Handler
	// contains filtered or unexported fields
}

Filter represents a plugin instance that can filter and block requests based on predefined lists and regex rules.

func New

func New() *Filter

func (*Filter) Load

func (f *Filter) Load() error

func (*Filter) Match

func (f *Filter) Match(name string) bool

Match determines if the requested name should be blocked or allowed.

func (*Filter) Name

func (f *Filter) Name() string

Name implements the plugin.Handler interface.

func (*Filter) ServeDNS

func (f *Filter) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements the plugin.Handler interface.

type PatternMatcher

type PatternMatcher struct {
	// contains filtered or unexported fields
}

func NewPatternMatcher

func NewPatternMatcher() *PatternMatcher

func (*PatternMatcher) Add

func (f *PatternMatcher) Add(pattern string) error

func (*PatternMatcher) Load

func (f *PatternMatcher) Load(r io.Reader) error

func (*PatternMatcher) Match

func (f *PatternMatcher) Match(qname string) bool

type ResponseWriter

type ResponseWriter struct {
	dns.ResponseWriter
	*Filter
	// contains filtered or unexported fields
}

ResponseWriter is a response writer that performs response uncloaking.

func (*ResponseWriter) WriteMsg

func (w *ResponseWriter) WriteMsg(m *dns.Msg) error

WriteMsg implements the dns.ResponseWriter interface.