ads

README

CoreDNS - ads Plugin

DNS AdBlocker plugin for CoreDNS.

Compiling

First get the CoreDNS source code by running, after you cloned this repository into the proper path in your GOPATH

go get github.com/coredns/coredns

Then navigate to the coredns directory

cd $(go env GOPATH)/src/github.com/coredns/coredns

Next update the plugin.cfg in the root of the coredns repository as follows

sed -i 's|loadbalance:loadbalance|ads:github.com/c-mueller/ads\nloadbalance:loadbalance|g' plugin.cfg

while I would suggest having the ads plugin before the cache plugin because it will cause the changes in the blocklists to be applied instantly. However the overall performance of the DNS server could degrade when having many regex rules. In that case I recommend putting the plugin before the hosts plugin:

sed -i 's|hosts:hosts|ads:github.com/c-mueller/ads\nhosts:hosts|g' plugin.cfg

Finally run make to build CoreDNS with the ads plugin

The releases section also contains binaries of the latest CoreDNS with the ads plugin. These get built automatically using drone. Once they have been triggered.

Configuring

Default settings

Running the ads plugin with all defaults is done by just adding the ads keyword to your Corefile.

For example:

.:53 {
    ads
    forward . 1.1.1.1
    log
    errors
}

Configuring the ads plugin

You can see a more complex ads configuration in the following Corefile

.:53 {
   ads {
        list http://url-to-my-blocklists.com/list1.txt
        list http://url-to-my-blocklists.com/list2.txt
        default-lists
        blacklist google.com
        whitelist googleadservices.com
        target 10.133.7.8
        target-ipv6 ::1
   }
   # Other directives have been omitted
}

Configuration options

• list <LIST URL> HTTP(S)-URL to a hostlist to Block
• default-lists Readds the default hostlists to the internal list of blocklists.
  • This command is needed if you want to add custom blocklists and you want to also use the default ones
• target <IPv4 IP> defines the target ip to which blocked domains should resolve to if a A record is requested
• target-ipv6 <IPv6 IP> defines the target IPv6 address to which blocked domains should resolve to if a AAAA record is requested
• disable-auto-update Turns off the automatic update of the blocklists every 24h (can be changed)
• log Print a message every time a request gets blocked
• auto-update-interval <INTERVAL> Allows the modification of the interval between blocklist updates
  • This operation uses Golangs time.ParseDuration() function in order to parse the duration. Please ensure the specified duration can be parsed by this operation. Please refer to here.
  • This gets ignored if the automatic blocklist updates have been disabled
• blocklist-path <FILEPATH FOR PERSISTED BLOCKLIST> This option enables persisting of the blocklist to prevent a automatic redownload everytime CoreDNS restarts. The lists get persisted everytime a update get performed.
  • If autoupdates have been turned off the list will be reloaded every time the application launches. Making this option pretty useless for this kind of configuration.
• whitelist <QNAME> and blacklist <QNAME> Allows the explicit whitelisting or blacklisting of specific qnames. If a qname is on the whitelist it will not be blocked.
• whitelist-regex <REGEX> and blacklist-regex <REGEX> identical to the regular whitelist and blacklist options. But instead of blocking a specific qname blocking is done for a regular expression. Yo might want to define exceptions to a regex blacklist entry. This can be done by using eitehr the whitelist or whitelist-regex options.

Documentation

Index

• type BlockMap
  • func GenerateBlockageMap(blocklistUrls []string) (BlockMap, error)
• type BlocklistUpdater
  • func (u *BlocklistUpdater) Start()
• type DNSAdBlock
  • func (e *DNSAdBlock) Name() string
  • func (e *DNSAdBlock) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
• type RuleSet
  • func BuildRuleset(whitelist, blacklist []string) RuleSet
  • func (r *RuleSet) AddRegexToBlacklist(regex string) error
  • func (r *RuleSet) AddRegexToWhitelist(regex string) error
  • func (r *RuleSet) AddToBlacklist(qname string)
  • func (r *RuleSet) AddToWhitelist(qname string)
  • func (r *RuleSet) IsBlacklisted(qname string) bool
  • func (r *RuleSet) IsWhitelisted(qname string) bool
• type StoredBlocklistConfiguration
  • func ReadBlocklistConfiguration(path string) (*StoredBlocklistConfiguration, error)
  • func (s *StoredBlocklistConfiguration) NeedsUpdate(updateDuration time.Duration) bool
  • func (s *StoredBlocklistConfiguration) Persist(path string) error

Types

type BlockMap

type BlockMap map[string]bool

func GenerateBlockageMap

func GenerateBlockageMap(blocklistUrls []string) (BlockMap, error)

type BlocklistUpdater

type BlocklistUpdater struct {
	Enabled        bool
	UpdateInterval time.Duration
	RetryCount     int
	RetryDelay     time.Duration

	Plugin *DNSAdBlock
	// contains filtered or unexported fields
}

func (*BlocklistUpdater) Start

func (u *BlocklistUpdater) Start()

type DNSAdBlock

type DNSAdBlock struct {
	Next       plugin.Handler
	BlockLists []string
	RuleSet    RuleSet
	// contains filtered or unexported fields
}

func (*DNSAdBlock) Name

func (e *DNSAdBlock) Name() string

Name implements the Handler interface.

func (*DNSAdBlock) ServeDNS

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

type RuleSet

type RuleSet struct {
	Blacklist      map[string]bool
	Whitelist      map[string]bool
	WhitelistRegex []*regexp.Regexp
	BlacklistRegex []*regexp.Regexp
}

func BuildRuleset

func BuildRuleset(whitelist, blacklist []string) RuleSet

func (*RuleSet) AddRegexToBlacklist

func (r *RuleSet) AddRegexToBlacklist(regex string) error

func (*RuleSet) AddRegexToWhitelist

func (r *RuleSet) AddRegexToWhitelist(regex string) error

func (*RuleSet) AddToBlacklist

func (r *RuleSet) AddToBlacklist(qname string)

func (*RuleSet) AddToWhitelist

func (r *RuleSet) AddToWhitelist(qname string)

func (*RuleSet) IsBlacklisted

func (r *RuleSet) IsBlacklisted(qname string) bool

func (*RuleSet) IsWhitelisted

func (r *RuleSet) IsWhitelisted(qname string) bool

type StoredBlocklistConfiguration

type StoredBlocklistConfiguration struct {
	UpdateTimestamp int      `json:"update_timestamp"`
	Blocklists      []string `json:"blocklists"`
	BlockedNames    BlockMap `json:"blocked_names"`
}

func ReadBlocklistConfiguration

func ReadBlocklistConfiguration(path string) (*StoredBlocklistConfiguration, error)

func (*StoredBlocklistConfiguration) NeedsUpdate

func (s *StoredBlocklistConfiguration) NeedsUpdate(updateDuration time.Duration) bool

func (*StoredBlocklistConfiguration) Persist

func (s *StoredBlocklistConfiguration) Persist(path string) error