oznu / docker-dns-ad-blocker

A lightweight dnsmasq DNS server to block traffic to known ad servers with optional DNSCrypt support. Supports x86_64 and Raspberry Pi (armhf).

oznu/dns-ad-blocker

A simple, lightweight, dnsmasq DNS server to block traffic to known ad servers.

Image Variants

Image Tag	Architecture	OS	Size
latest	x64	Alpine Linux
armhf	arm32v6	Alpine Linux
aarch64	arm64	Alpine Linux

Usage

Quick Setup:

docker run -d -p 53:53/tcp -p 53:53/udp oznu/dns-ad-blocker

Raspberry Pi:

docker run -d -p 53:53/tcp -p 53:53/udp oznu/dns-ad-blocker:armhf

You can now set your devices to use the Docker Host's IP Address as the primary DNS resolver, if you are using Docker for Windows or Docker for Mac this will be 127.0.0.1.

Automatic blacklist updates are enabled by default.

Parameters

docker run --restart=always \
  -p 53:53/tcp -p 53:53/udp \
  -e DEBUG=0 \
  -e NS1=1.1.1.1 -e NS2=1.0.0.1 \
  -e AUTO_UPDATE=1 \
  -e BRANCH=master \
  -e DNSCRYPT=0 \
  -v </path/to/config>:/config \
  oznu/dns-ad-blocker

The parameters are split into two halves, separated by a colon, the left hand side representing the host and the right the container side.

• --restart=always - ensure the container restarts automatically after host reboot.
• -p 53:53/tcp -p 53:53/udp - expose port 53 on TCP and UDP to the host, required.
• -e DEBUG - enables debug mode if set to -e DEBUG=1. For verbose logging (including source IP) set -e DEBUG=2.
• -e NS1 -e NS2 - override the default forward lookup servers. Defaults to Cloudflares's DNS servers (1.1.1.1, 1.0.0.1).
• -e AUTO_UPDATE - to disable automatic updates to the blacklist set -e AUTO_UPDATE=0. Automatic updates are enabled by default.
• -e BLACKLIST_URL - the url where the blacklist should be downloaded from, useful if you want to lock the blacklist to a specific branch.
• -e WHITELIST - a list of domains to exclude from the blacklist (comma separated, no spaces) eg. -e WHITELIST=www.oz.nu,hub.docker.com
• -e DNSCRYPT=1 - enable DNSCrypt, disabled by default. See below for more details.
• -v /config - any files with the .conf suffix included in the mounted volume will be included in the dnsmasq config.

AD Blocking

This image is using the blacklists created by oznu/dns-zone-blacklist and StevenBlack/hosts.

The DNS server works by returning NXDOMAIN when a DNS lookup is made by a browser or device to a blacklisted domain. This tells the browser the DNS record for domain name could not be found which means the browser won't even attempt a connection.

If you have found a host you think should be blacklisted please submit an issue on the upstream blacklist, StevenBlack/hosts, as the aim of this project is not to maintain yet another blacklist.

DNSCrypt

DNSCrypt is a protocol that authenticates communications between a DNS client and a DNS resolver. It uses cryptographic signatures to verify that responses originate from the chosen DNS resolver and haven't been tampered with.

Note: Using DNSCrypt does not increase your privacy online and is not a replacement for a VPN. Even if you’re using HTTPS, your browser is sending the website hostname in plain text due to SNI.

This image allows you to enable DNSCrypt for your entire local network or individual workstation without having to install any other client software.

docker run  -d --restart=always -p 53:53/tcp -p 53:53/udp -e DNSCRYPT=1 oznu/dns-ad-blocker

• -e DNSCRYPT - To enable DNSCrypt set DNSCRYPT=1. Disabled by default.
• -e DNS_CRYPT_SERVERS - a comma seperated (no spaces) list of servers to use. Defaults to cloudflare,cloudflare-ipv6.

Enabling DNSCrypt will override the NS1 and NS2 forward lookup server options.

See the offical list of DNSCrypt resolvers for alternative providers if you don't want to use Cloudflare DNS.