Introducing dns-blackhole

So the other day I wanted to remove ads on my Android phone, but apparently you can't install extensions on Android chromium and I didn't feel like using Firefox for that.
Since I use non rooted CopperHeadOS as my main mobile OS, solutions like AdAway that require root access were not possible either.... What to do then?
Oh wait don't we have a recursive DNS resolver on this OpenVPN tunnel? We sure do! And wouldn't it be nice that it removes ads for us? Indeed it would!

On this particular setup I was using PowerDNS Recursor and so stumbled upon this nice blog article from last year where they explain how to use the Disconnect list used by the Mozilla Focus project to efficiently block ads/tracking domains.

While the process is quite easy, after reading some of the project readme it seemed even more simple to just get the domains from the original list.
I thus wrote this tiny script that would do the job for me, without even touching the Git repo from the blog post, and PowerDNS Recursor was now happily blocking DNS queries to some advertisement and tracking domains...
Some seemed suddenly too few... With the ~1500 domains that the Disconnect list was offering, I was only blocking a tiny fraction of the trash that most of Internet has become today. We could surely do better :)

I decided that it would be interesting to include the content of several well known host lists and ended up with more than 690000 domains blocked!!
That sure was some improvement, but this proved the lua method to be unable to cope with that many entries - recursor crashed at startup with a constant overflow - so I searched how to make recursor behave correctly while still be able to block all those bad domains.
The idea has been to generate a zone file that would respect recursor's syntax and that could be fed through the forward-zones-file option.
Syntax looks like this:

<domain>=<where to forward the query>

The nice thing here is that if you don't specify any <where to forward the query>, recursor will directly reply with a NXDOMAIN answer.
That's perfect! For all those bad domains my client would receive a NXDOMAIN return and wouldn't even try to connect anywhere. Exactly what was needed!

So basically if we can make a file with one domain per line for PowerDNS Recursor, we should be able to do so for other DNS servers...

After a major cleanup, here comes dns-blackhole!


  • Not bound to a specific DNS server, generates a file format of your choice
  • Supports 3 different list format
  • Lets you whitelist/blacklist domains
  • YAML configuration file
  • Easy installation with pip

It has been successfully tested with:

Even generating an agregated host file is possible.

The project's README covers pretty much every details needed to use it, just keep in mind that without a whitelist your browsing sessions will lack a lot of content.
Here's a short whitelist example: # Skype CDN #

And indeed you'll have to re-run dns-blackhole each time you add something to the whitelist.

I hope you'll find this tool useful, and as usual feel free to contact me should you have any questions.