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
  • Capable of generating and exporting 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 undesireable online content across your entire network. unbound-adblock works even with locked-down/walled-garden devices that are incapable of using traditional content filtering methods. unbound-adblock is known to to boost web browsing speed and increase battery life on many devices.

In short: unbound-adblock is able to block huge amounts of online trackers, malware, fake sites, pop ups and other annoying garbage.

unbound-adblock takes a different approach from that of traditional browser-based adblockers such as uBlock Origin, Adblock Plus etc. As such, use of unbound-adblock incurs no additional CPU utilization on client-side devices as all the heavy lifting is done by the DNS server. In many cases it can actually reduce client-side CPU usage due to the filtering/removal of heavy ad and tracking scripts on the web. For devices with limited resources, unbound-adblock can be a breath of fresh air.

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.

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
  • Stefan Schmidbauer
  • Brandon W.

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.

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

A-3: 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: Why should I use this instead of [/etc/hosts, PiHole, dnsmasq etc]

A-4: I'm not here to tell you what to do. I made something that fits my needs and brings me (and hopefully others) joy. I've made an effort to strike a balance between brutal functional minimalism and friendly enough user interface. If it does not bring you joy or satisfaction, then feel free to improve it or seek out greener pastures.

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

A-5: 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