The Ultimate DNS Firewall!

Version 0.5 Released!

January 10, 2021

Table of Contents

Platform Install Instructions:

OpenBSD | OpenBSD-unwind | FreeBSD | DragonflyBSD | NetBSD | SystemD/Linux | Alpine Linux

Download Link: unbound-adblock.sh | Previous Releases: Archives

Changelog: changelog.txt

Man Page: man.txt

Beta Snapshots: beta

Errata (instructions are within patch file):
001 , 002 , 003 , 004 , 005

tl;dr Feature List

  • Highly customizable DNS firewall powered by Unbound
  • Highly portable - supports nearly every Linux and BSD OS
  • Blocklist automatically updates so you always have the latest blocklist data
  • Improves privacy - blocks many analytics and tracking severs and can prevent IoT devices and other garbage from phoning home
  • Removes ads and analytics from apps and other proprietary services/programs while improving battery life on mobile devices
  • Enables you to block ads on traditionally locked down devices:
    • Mobile: Phones, Tablets, iPads, Android boxes etc
    • Media players: Chromecasts, Firestick, Roku, AppleTV etc
    • IoT Devices: 'smart' TVs, crappy networking devices etc
  • User configurable block lists
  • Encryption: Uses DNS over TLS (DoT) by default
  • Supports /etc/hosts format and domain-only blocklists
  • Can block ads from a router or server with unbound or on a personal device with unwind
  • Can be used for generating RPZ blocklists suitable for ingestion by DNS server software such Unbound, BIND, PowerDNS and Knot Resolver.


Unbound-adblock is a fast, flexible, easy to use DNS firewall utility. It allows you to block online advertisements network wide and thus block ads on devices that otherwise don't support traditional browser-based adblockers such as uBlock Origin, Adblock Plus etc. I have found unbound-adblock to boost web browsing speed and increase battery life on mobile devices.

A nice side effect of the network adblocking is that there is no added CPU utilization on the client-side device for filtering out the ads, as all the heavy lifting is done by the DNS server. For devices with limited resources, unbound-adblock can be a breath of fresh air.

Additionally, unbound-adblock blocks a large amount of online trackers, malware, fake sites, pop ups and other annoying garbage.

unbound-adblock works best when used in conjunction with pf-badhost

To receive notifications for new unbound-adblock releases, send an email to announce@geoghegan.ca with this subject line: "subscribe unbound-adblock"

If you believe my work has provided value to you, and if you have the means to, please consider donating. I'm fairly poor, so every little bit helps.

If you want to donate, but aren't able to use PayPal, please get in contact with me and we can figure out a more suitable method.


I would like to give thanks to the following people for their donations of time, resources and/or money to the project:

  • Pedro Guizeline
  • Paulo Rodriguez
  • Thomas K.
  • James K.
  • Steven Caesare
  • Marcus Merighi
  • Ethan Ferguson
  • Nate Rogers
  • Maurice McCarthy
  • Chris Armstrong

Thanks to Mischa Peters and OpenBSD Amsterdam for sponsoring the project! They were kind enough to offer the project free computing resources to help facilitate development and testing of unbound-adblock.

Thanks to Sean Davies for his numerous code and manpage improvements. Thanks for the all the diffs!

What Folks Are Saying:

If you've written or created something related to unbound-adblock and would like to have your link listed here then please send me an email.


OpenBSD Router Guide

DragonflyBSD Digest

Mischa Peters of OpenBSD Amsterdam

  • Been a fan of unbound-adblock since version 0.2, and every version keeps on getting better! Version 0.5 is by far the best version to date. The easy installation steps, talking into account people still running older OpenBSD releases, support for unwind, and the move to RPZ for Unbound is a joy. The allowlist function is a very nice workaround to make specific sites working, like slack, without removing a complete blocklist from the feeds. It’s great to see unbound-adblock evolve and remain rock-solid. Thank you Jordan for doing this!

Frequently Asked Questions

Q-1: How can I help the project?

A-1: You can find bugs, donate, or tell your friends about unbound-adblock.

Q-2: Will this run on Linux?

A-2: Yes, unbound-adblock should run on pretty much any Unix-like OS that has Unbound available.

Q-4: How do I check unbound-adblock's status?

A-4: By default, unbound-adblock sends all log messages to syslog and also prints them to stderr. A copy of the two most recently generated blocklists are stored within '/var/log/unbound-adblock'. These behaviors can be modified using commandline options.

Additionally, most cron daemons are configured to mail the cron job results/output to the cron job owner. If you have your local mail system configured on your machine, you can configure the status reports to be forwarded to your main email account. Please check the documentation relevant to your system for more info, as this is beyond the scope of unbound-adblock's instuctions.

Q-4: Can't I just run this as root?

A-4: I'd tell you to stop being annoying, but you have a right to shoot yourself in the foot. You can use the '-D' option to disable UID checking.

Previous Release Pages