Awesome Open Source
Awesome Open Source

Travis Docker Pulls


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


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

Automatic blacklist updates are enabled by default.


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

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 (,
  • -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,
  • -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 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.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Docker (33,984
Dockerfile (28,326
Cross Platform (3,288
Privacy (1,976
X86 64 (515
Alpine Linux (434
Arm64 (360
Dns Server (329
Blacklist (263
Aarch64 (262
Dnsmasq (180
Related Projects