split

README

split

Name

split - Filter DNS Server response Records based on network definitions and request source IP.

Description

The split plugin allows filtering DNS Server responses Records based on network definitions. That way you do not need to run multiple DNS servers to handle split DNS.

If there are multiple A Records in the response, only the records matching the defined network will be returned to a matching querier, and the records not matching the network to the other sources.

⚠️ This plugin is not much about security, it is designed only to give a better answer to the incoming source IP, if you need to apply security filtering rules, please consider using the coredns acl plugin.

Compilation

This package will always be compiled as part of CoreDNS and not in a standalone way. It will require you to use go get or as a dependency on plugin.cfg.

The manual will have more information about how to configure and extend the server with external plugins.

A simple way to consume this plugin, is by adding the following on plugin.cfg, and recompile it as detailed on coredns.io.

split:go.linka.cloud/coredns-split

Put this higher in the plugin list, so that split is before after any of the other plugins.

After this you can compile coredns by:

go generate
go build

Or you can instead use make:

make

Syntax

split
# TODO: docs

Ready

This plugin reports readiness to the ready plugin. It will be immediately ready.

Examples

In this configuration, we forward all queries to 10.10.10.1 and to 9.9.9.9 if 10.10.10.1 did not respond.

If only used with the forward plugin, the private dns server must be configured as the first forwarded server in the list. The policy must be configured as sequential, so that the first server is always tried first and the second only if the first do not return any answer.

We filter out A / CNAME / SRV / PTR records pointing to an IP address in the 10.10.10.0/24 network except for queries coming from the 192.168.0.0/24 and 192.168.1.0/24 networks. If the allowed networks are not defined, the plugin will allow the requests from the same network, e.g. 10.10.10.0/24.

If the record exists both as public and private, the private record will be filtered, resulting with no records at all. So you can provide a fallback server that will be used to get the public record.

. {
  split {
    net 10.10.10.0/24 allow 192.168.0.0/24 192.168.1.0/24
    net 10.1.1.0/24 10.1.2.0/24 # implicitely: allow 10.1.1.0/24 10.1.2.0/24
    fallback 8.8.8.8
  }
  # we could also use any records source
  # e.g.: file example.org
  forward . 10.10.10.1 9.9.9.9 {
    policy sequential
  }
}

Also See

See the manual.

Documentation

Overview

Package split is a CoreDNS plugin that prints "example" to stdout on every packet received.

It serves as an example CoreDNS plugin with numerous code comments.

Index

• type Network
• type ResponsePrinter
  • func (r *ResponsePrinter) WriteMsg(res *dns.Msg) error
• type Rule
• type Split
  • func (s Split) Name() string
  • func (s Split) NewResponsePrinter(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) *ResponsePrinter
  • func (s Split) Ready() bool
  • func (s Split) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

Types

type Network

type Network struct {
	RecordNetwork *net.IPNet
	Allowed       []*net.IPNet
}

type ResponsePrinter

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

ResponsePrinter wrap a dns.ResponseWriter and will write example to standard output when WriteMsg is called.

func (*ResponsePrinter) WriteMsg

func (r *ResponsePrinter) WriteMsg(res *dns.Msg) error

WriteMsg calls the underlying ResponseWriter's WriteMsg method and prints "example" to standard output.

type Rule

type Rule struct {
	Zones    []string
	Networks []Network
	Fallback net.IP
}

type Split

type Split struct {
	Next plugin.Handler

	Rules []Rule
}

Split is an example plugin to show how to write a plugin.

func (Split) Name

func (s Split) Name() string

Name implements the Handler interface.

func (Split) NewResponsePrinter

func (s Split) NewResponsePrinter(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) *ResponsePrinter

NewResponsePrinter returns ResponseWriter.

func (Split) Ready

func (s Split) Ready() bool

Ready implements the ready.Readiness interface, once this flips to true CoreDNS assumes this plugin is ready for queries; it is not checked again.

func (Split) ServeDNS

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

ServeDNS implements the plugin.Handler interface. This method gets called when example is used in a Server.