Block online ads by intercepting DNS queries

Overview

donutdns

Block online ads by intercepting DNS queries

Go Report Card Build Status GoDoc NetflixOSS Lifecycle License

Project Overview

The gophers.dev/cmds/donutdns module provides a CoreDNS plugin as well as a standalone executable DNS server that can be used to block DNS queries to domains used by online advertisers, trackers, scammers, and crypto miners. The project is meant to be a simpler alternative to the venerable Pi-Hole. In particular, donutdns is easy to run as a non-root Docker container with little to no configuration.

sample logs

[INFO] plugin/donutdns: BLOCK query (A) for www.google-analytics.com.
[INFO] plugin/donutdns: BLOCK query (A) for www-google-analytics.l.google.com.
[INFO] plugin/donutdns: BLOCK query (A) for stats.wp.com.
[INFO] plugin/donutdns: BLOCK query (A) for www.googletagservices.com.
[INFO] plugin/donutdns: BLOCK query (A) for tpc.googlesyndication.com.
[INFO] plugin/donutdns: BLOCK query (A) for c.amazon-adsystem.com.
[INFO] plugin/donutdns: BLOCK query (A) for static.ads-twitter.com.

Domain Block Lists

The default set of blocked domains are retrieved from the source lists in sources.json. These lists are compiled and maintained by volunteers; see their respective headers for more information about terms of use and other metadata. Thank you to those who contribute to these domain block lists.

The blocking of the default set of domains can be disabled by setting DONUT_DNS_NO_DEFAULT=1.

Additional domains can be blocked by donutdns by setting the DONUT_DNS_BLOCK and/or DONUT_DNS_BLOCK_FILE environment variables.

Likewise, domains can be explicitly allowed by setting the DONUT_DNS_ALLOW and/or DONUT_DNS_ALLOW_FILE environment variables. The allow lists take precedense over the block lists.

(!) Currently donutdns does not support wildcard subdomain blocking. Each subdomain to be blocked will also need to be added. (e.g. example.com and www.example.com)

Getting Started

donutdns can be used as a CoreDNS Plugin or standalone DNS Server.

DNS Server

The donutdns executable uses environment variables for configuration.

Environment Variable Description
DONUT_DNS_PORT The port to listen to (default 5301)
DONUT_DNS_NO_DEBUG Disable CoreDNS debug logging (default unset)
DONUT_DNS_NO_LOG Disable CoreDNS logging (default unset)
DONUT_DNS_ALLOW Comma separated list of domains to NOT block (default unset)
DONUT_DNS_ALLOW_FILE File with list of domains to NOT block (default unset)
DONUT_DNS_BLOCK Comma separated list of domains to block (default unset)
DONUT_DNS_BLOCK_FILE File with list of domains to block (default unset)
DONUT_DNS_NO_DEFAULTS Disable blocking of default domain block lists (default unset)
DONUT_DNS_UPSTREAM_1 Fallback DNS Server for non-blocked queries (default 1.1.1.1)
DONUT_DNS_UPSTREAM_2 Fallback DNS Server for non-blocked queries (default 1.0.0.1)
DONUT_DNS_UPSTREAM_NAME Fallback DNS Server TLS name (default cloudflare-dns.com)

CoreDNS Plugin

The donutdns CoreDNS plugin is configured using the donutdns block in a standard CoreConfig configuration file.

Minimal donutdns plugin configuration. defaults can be set to true or false to enable or disable the use of default domain block lists.

donutdns {
  defaults true
}

This configuration uses block_file to explicitly block a set of domains listed in a file on local disk.

donutdns {
  defaults false
  block_file /etc/blocked-domains.txt
}

This configuration uses block and allow to explicitly block and allow certain domains.

donutdns {
  defaults true
  block facebook.com,www.facebook.com,m.facebook.com,fb.com
  allow example.com
}

When using donutdns as a CoreDNS plugin, the fallthrough behavior must be configured as desired using one or more other plugins. To recreate the same recursive behavior as the standalone executable, use the forward plugin.

forward . 1.1.1.1 1.0.0.1 {
  tls_servername cloudflare-dns.com
}

Custom block file

The file format for block_file or DONUT_DNS_BLOCK_FILE is simply a newline delimited list of domains. Empty lines and lines beginning with # are always ignored. All other lines are scanned with a regular expression to find the first plausible domain name in the line. social-media.list contains an example file for blocking facebook, instagram, and whatsapp.

# An example block list
example.com
www.example.com

Run

as an executable

With no configuration, donutdns will use the built-in domain block lists by default.

$ donutdns

Use the environment variables described above to configure things.

$ DONUT_DNS_PORT=5533 DONUT_DNS_NO_DEBUG=1 donutdns

as a docker container

donutdns is available from Docker Hub

This will run the donutdns Docker container as the nobody user, mapping traffic from port 53.

docker run --rm -p 53:5301 -u nobody shoenig/donutdns:v0.1.2

as a Nomad job

using docker driver
job "donutdns" {
  datacenters = ["dc1"]

  group "donut" {
    network {
      mode = "bridge"
      port "dns" {
        static       = 53
        to           = 5301
        host_network = "public"
      }
    }

    task "dns" {
      driver = "docker"
      user   = "nobody"

      resources {
        cpu    = 120
        memory = 64
        disk   = 128
      }

      env {
        DONUT_DNS_NO_DEBUG   = 1
        DONUT_DNS_BLOCK_FILE = "/local/blocks.txt"
      }

      config {
        image = "shoenig/donutdns:v0.1.2"
      }

      template {
        destination = "local/blocks.txt"
        change_mode = "restart"
        perms       = "644"
        data        = <<EOH
# [example]
example.com
www.example.com
EOH
      }
    }
  }
}

Build

The donutdns standalone DNS Server is written in Go. It can be compiled and installed using the normal Go toolchain in one step.

go install gophers.dev/cmds/[email protected]

Contributing

The gophers.dev/cmds/donutdns module is always improving with new features and bug fixes. For contributing such bug fixes and new features please file an issue.

License

The gophers.dev/cmds/donutdns module is open source under the BSD-3-Clause license.

Issues
  • bootstrap using configured upstreams

    bootstrap using configured upstreams

    https://github.com/shoenig/donutdns/blob/24efd9b415eb4138913705975ce7ff03b09d0f58/sources/fetch/client.go#L24

    Use the UPSTREAM_0 for the initial bootstrapping of source lists

    opened by shoenig 0
Owner
Seth Hoenig
Seth Hoenig
A simple DNS forwarder that forwards DNS queries to various upstreams

A simple DNS forwarder that forwards DNS queries to various upstreams. If an upstream returns NXDomain, the next upstream is tried.

null 1 May 10, 2022
Header Block is a middleware plugin for Traefik to block request and response headers which regex matched by their name and/or value

Header Block is a middleware plugin for Traefik to block request and response headers which regex matched by their name and/or value Conf

null 3 May 24, 2022
Hetzner-dns-updater - A simple tool to update a DNS record via Hetzner DNS API. Used for simple HA together with Nomad

hetzner-dns-updater A small utility tool to update a single record via Hetzner D

Patrick Pacher 0 Feb 12, 2022
Access Google Ads API via GRPC

google-ads-pb You can use the golang library to interact with the Google Ads API across grpc. This library is not the official Google Ads API library.

null 9 Jun 10, 2022
GoLang ads.txt scraper

Collects and parses ads.txt GoLang program scrapes sites for ads.txt and stores its significant details to PostgreSQL database. Give it a file with CS

null 0 Feb 11, 2022
DNS Ping: to check packet loss and latency issues with DNS servers

DNSping DNS Ping checks packet loss and latency issues with DNS servers Installation If you have golang, easiest install is go get -u fortio.org/dnspi

Fortio (Φορτίο) 55 May 30, 2022
Verify IP addresses of respectful crawlers like Googlebot by reverse dns and forward dns lookups

goodbots - trust but verify goodbots verifies the IP addresses of respectful crawlers like Googlebot by performing reverse dns and forward dns lookups

Eric Wu 29 Jun 21, 2022
The Dual-Stack Dynamic DNS client, the world's first dynamic DNS client built for IPv6.

dsddns DsDDNS is the Dual-Stack Dynamic DNS client. A dynamic DNS client keeps your DNS records in sync with the IP addresses associated with your hom

Ryan Young 10 Jun 20, 2022
netcup DNS module for caddy: dns.providers.netcup

netcup DNS module for Caddy This package contains a DNS provider module for Caddy. It can be used to manage DNS records with the netcup DNS API using

null 6 Mar 3, 2022
A fork on miekg/dns (since I've already forked zmap/dns)

Alternative (more granular) approach to a DNS library Less is more. Complete and usable DNS library. All Resource Records are supported, including the

null 0 Jan 19, 2022
A CLI tool queries the GitHub GraphQL API for users and ranks them according to number of contributions

Project homepage Most Active GitHub Users Counter This CLI tool queries the GitHub GraphQL API for users and ranks them according to number of contrib

Mike Owino 0 Dec 6, 2021
An online shop application, the complete microservices demo for kratos.

[WIP] beer-shop An online shop application, the complete microservices demo for kratos. 本项目为一个使用kratos框架创建的,简单却功能尽量完整的微服务电商项目。旨在演示kratos在mono-repo(单体仓

Kratos 438 Jun 24, 2022
Backend implementation using go, proto3 and gRPC for a mock online store

Backend implementation using go, proto3 and gRPC for a mock online store Ricardo RICO URIBE Tasks I - Order service The current system exposes a produ

Ricardo Rico 0 Oct 10, 2021
Proxy that keeps clients active until the backend server is back online

HoneySmoke HoneySmoke is a prototype proxy for testing until it eventually becomes HoneyHive. HoneySmoke will eventually implement a limbo mode that k

Ethan 4 Nov 20, 2021
Inventory: Task 1 : Online Store

Task 1 : Online Store ### Q1: Describe what you think happened that caused those bad reviews during our 12.12 event and why it happened. Answer : You

Randhi Pratama Putra 0 Dec 6, 2021
Subfinder is a subdomain discovery tool that discovers valid subdomains for websites by using passive online sources

Subfinder is a subdomain discovery tool that discovers valid subdomains for websites. Designed as a passive framework to be useful for bug bounties and safe for penetration testing.

ProjectDiscovery 5.8k Jul 1, 2022
DNS library in Go

Alternative (more granular) approach to a DNS library Less is more. Complete and usable DNS library. All Resource Records are supported, including the

Miek Gieben 6.4k Jun 30, 2022
A client software for acme-dns with emphasis on usability and guidance through setup and additional security safeguard mechanisms

acme-dns-client A client software for acme-dns with emphasis on usability and guidance through setup and additional security safeguard mechanisms. It

null 60 Jun 9, 2022
A tiny command line DNS client with support for UDP, DoT, DoH, and DoQ.

q A tiny command line DNS client with support for UDP, DoT, DoH, and DoQ. Usage q command line DNS client (https://github.com/natesales/q) Usage: q

Nate Sales 670 Jun 28, 2022