A simple, lightweight, Dnsmasq DNS server to block traffic to known ad servers.
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 26 commits behind oznu:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
config
init.d
.dockerignore
Dockerfile
README.md
_config.yml

README.md

Docker Automated buil Docker Pulls

oznu/dns-ad-blocker

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

Usage

Quick Setup:

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

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. This should only be used on conjunction with a restart policy as the container is killed when an update is available to refresh Dnsmasq.

Parameters

docker run -d --restart=always
  -p 53:53/tcp -p 53:53/udp
  -e DEBUG=0
  -e NS1=8.8.8.8-e NS2=8.8.4.4
  -e AUTO_UPDATE=1
  -e BRANCH=master
  -v </path/to/config>:/etc/dnsmasq.d/
  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 an update, required.
  • -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 DEBUG=1. For verbose logging (including source IP) set DEBUG=2.
  • -e NS1 -e NS2 - override the default forward lookup servers. By default these are set to Google's DNS servers.
  • -e AUTO_UPDATE - to disable automatic updates to the blacklist set AUTO_UPDATE=0. Automatic updates are enabled by default.
  • -e BRANCH - set the branch or commit to use for the blacklist. Defaults to master.
  • -v /etc/dnsmasq.d/ - any files included in the mounted volume will be included in the Dnsmasq config. See below.

AD Blocking

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

The DNS server works by returning 0.0.0.0 when a DNS lookup is made by a browser or device to a blacklisted domain. 0.0.0.0 is defined as a non-routable meta-address used to designate an invalid, unknown, or non applicable target which results in the browser rejecting the request.

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.

Optional :: Custom Domains

This image supports adding additional zones that may be used to serve internal DNS zones or to override existing zones.

To do this create a volume share when creating the container:

docker run -d -p 53:53/tcp -p 53:53/udp -v /srv/zones:/etc/dnsmasq.d/ oznu/dns-ad-blocker

Every file in the /srv/zones will be included as an extension to the Dnsmasq config.

Example:

# Add domains which you want to force to an IP address here.
# The example below send any host in doubleclick.net to a local
# webserver.
address=/doubleclick.net/127.0.0.1

# Return an MX record named "maildomain.com" with target
# servermachine.com and preference 50
mx-host=maildomain.com,servermachine.com,50

After adding or updating a zone config file you must restart the container for it to be loaded.