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

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

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
        target 10.133.7.8
   }
   # 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
• 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.

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 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
	TargetIP   net.IP
	LogBlocks  bool
	// 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 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