Friday, November 29, 2019

The easiest way to build a Pi-hole, a low cost, low power, network-level ad blocker

As we all know the internet has a lot of advertising these days.  You could even say the internet has become infected with full blown ADS. One solution to this is an ad blocking add-on for your browser.  Another solution however is to create a small dedicated computer on your network that will do the same job.  The advantage of this is the ads are blocked at the network level, so not only is your browser protected, but all applications that request ads on all of your devices on your network will have their ad requests blocked. This single solution will block ads across all your devices and applications, rather than a browser ad blocker that works only within the browser, and only on each device where it's installed.

Do you need this ad blocker? No you can just use a browser ad blocker if you want, they do the same thing.  However, if you want to reduce your exposure to ads or are looking to understand Raspberry Pi for the first time, this is a good small project you can complete in a few hours.

How does it work? Typically most web pages don't have ads directly within them. Instead ads are pulled from other websites that specialize in delivering ads such as When a computer requests content from, that dot com domain name must be looked up on a list to find its numerical address, a number that computers can understand and route across the network. This process of finding the number addresses of name addresses is called Domain Name Resolution (?), and the computer that performs this task is called a Domain Name Server, or DNS for short. For example the name "" will be resolved by a DNS server to the numerical address   So if you create your own Domain Name Server on your network that never gives the numerical address of, you can block all content from, and therefore all ads from that site. This process is known as DNS sinkholing, which simply means that if a request is made for content from a domain name that is on a list of known ad websites, then no numerical address is returned for that website and it computers can't find it. The domain name request simply disappears into a "sinkhole", never to be seen again, hence the name. The effect to the user is that ads from that website won't appear on the web page they're browsing.

Another advantage is that you save some internet bandwidth by not downloading the ads, thus making your browsing experience a little faster, and the amount of material you download from the internet is less.

The best established free DNS sinkholing software is called Pi-hole. This software keeps a list of known ad websites and will block DNS requests for any that are in the list.

Everything you need to know about Pi-hole can be found at

Pi-hole runs on Linux. While Linux may seem intimidating to some people, the setup process for Pi-hole is actually very simple. 

On this page I supply detailed step-by-step instructions on how to make a low cost network-level ad blocker using a Raspberry Pi Zero W and Pi-hole.  There are many other web sites out there that will give you instructions on how to setup Pi-hole, but my instructions are intended to be as accurate, simple, and effective as possible, for people who may never have used Linux before.

The instructions may seem to have many steps but you're actually just installing the operating system, installing Pi-hole, and configuring the setup.  You will find the steps are as short and educational as possible.

There is one step in the setup where you will need to change the DNS addresses of your router. Consult your router's instructional manual for how to do this.  Most routers these days have a simple web interface or phone app for changing settings. If you're still confused, remember that the company who made your router probably has a free customer service phone number that you should use.

This blog post is the first in a series of two about setting up this ad blocker. In this post I'll show you how to setup Pi-hole on your WiFi network and get it working.
In the second post, I'll show you how to turn it into a stand alone device, cabled directly to your router, requiring no maintenance, and which uses the absolute minimum amount of electricity possible.  Here is the second post if you want to skip ahead:

Hardware needed

The first step is to get your hands on a complete Raspberry Pi Zero W kit.  These can be purchased at online electronics stores. Here is the one I bought from Amazon.

This kit contains most of the parts needed to setup your Raspberry Pi, including HDMI video cable, SD memory card loaded with NOOBS (New Out Of the Box Software), USB hub, and a case.  This kit has a clear case but you can also get the same kit in a black case.  The only advantage of a clear case is that you can see the power/activity light on the board of the Raspberry Pi, which lets you know if it's actually turned on and doing something. You can choose the black case if you want.  There are other brands of Raspberry Pi Zero W kits available as well. Be sure to get the Pi Zero W and not just the Pi Zero.  The Pi Zero W has additional WiFi and Bluetooth connectivity, and you will need the WiFi for the initial setup.

Some extra parts
  • This setup assumes you have an existing WiFi network to connect your Raspberry Pi. If not then it's probably time you checked out this new thing called the 21st century.
  • In addition to the kit, you will also need a USB keyboard and a USB mouse for the initial setup. If you don't have these then simply borrow them from somewhere. These will not be needed once the device is setup because you will be able to connect to your Pi remotely from your computer through the network.
  • A USB-A to USB-micro-B cable can also be useful if you want to power the board from something other than the power supply in the kit, e.g. from a USB port on your router. Note: I do not recommend powering your Pi from a USB port on your TV as the screen saver may send a signal to the TV to turn off, which will also power off your Pi.
  • For the fully cabled stand-alone version of the Raspberry Pi-hole that doesn't use the WiFi for its network connection, you will also need a micro-USB-to-ethernet adapter and a short ethernet cable. Depending on how you plan to power the device you might also need another USB cable for power. We will get to these items later when I explain the advantages and setup of a cabled system. To begin with you can just use Wifi because Pi-hole works just fine through a WiFi connection.

Build your Pi
  1. Remove the paper from the heat sink to expose the glue underneath. Place the heat sink onto the processor chip, making sure the metal of the heat sink doesn't contact any of the metal contacts of the other components on the board. You can use a magnifying glass or zoom in with your cell phone camera to make sure. The orientation of the fins on the heat sink is not important.
  2. Remove the four rubber feet from the paper and place into their locations on the bottom of the case. These feet are there to help your Pi stay still when sitting on a flat surface. Chances are the case will never sit flat anyway with all the cables attached, but you might as well use the feet since they're there.
  3. Insert the SD card into the slot.  Depending on how old your NOOBS is, the OS may need a lot of updates, which can take a lot of time.  If you have an SD card reader you can load the latest NOOBS onto the card from here.
    or you can load Raspberry Pi OS directly onto the card with the Raspberry Pi Imager:
    Your OS
    will still require updates but much less than an older version. I highly recommend starting with the latest Rapberry Pi OS if you can.
  4. Place the board into the case and put the lid on. There are three lids for the case. Use the one with no holes. The other lids are for a camera or GPIO header pins, but these lids will not be needed for this project.
  5. Plug the mini HDMI cable into the board and plug the other end into a TV or monitor that has a HDMI input.  Switch the input of your display to the appropriate HDMI port.
  6. Plug the USB hub into the USB port closest to the heat sink. Plug your keyboard and mouse into the USB hub.
  7. The Raspberry Pi Zero W has two USB ports.  The one closest to the heat sink is for data and peripherals such as your keyboard and mouse. The one at the far end of the board is only for power. It has no data connections and is only there to supply 5 volt power to the board. You can power this from any USB port if you have the right cable, or you can use the power supply in the kit.
  8. Power up your board. The Power/Activity light on the board should be lit and may start blinking.

Installing the operating system
  1. There should be something going on in your display as NOOBS (New Out Of the Box Software) loads.
  2. Once NOOBS loads, you will be presented with a list of operating systems to install, similar to the image below.  Don't worry if your list of operating systems isn't exactly the same as this one. Simply select Raspbian and then click the Install button at top left. You will be asked to Confirm that you want to overwrite the SD card, which is exactly what we want, so click Yes.

  1. The Raspbian operating system (OS) will now install. Be aware that it will take a long time, maybe 20 minutes or so, so go do something else for a while as the OS is installed.

  1. Once completed there will be a small window informing you "OS(es) installed successfully". Click OK.

  1. Raspbian will begin to load. First it will show a splash screen with a raspberry and a flashing cursor. Then there will be some text appear on the screen. Finally another splash screen will appear, and after a while some text at the bottom left will show various services that are being loaded. I've had this last part of the setup phase freeze once, so don't be afraid to turn off and on the Pi and restart the process if something takes way too long, you probably won't break anything.  Some services may take longer than others to load, so be patient.
  2. The desktop will load. Since this is the first time you have booted Raspbian, the initial setup window will appear. Press Next.

  1. Select your Country, Language, and Timezone, and press Next.
  2. For security reasons, I recommend changing the user password.  You will always be logging into your Raspberry as user "pi". The default password for pi is "raspberry".  Obviously this presents a security risk, so I recommend changing it.
  3. On the next screen your display will be optimized. Check the box if you see a black border around your desktop. 
  4. Next you will setup your WiFi network. Select your network and enter the password.
  5. The next window will want to update your operating system.  This requires a network connection to check your version of Raspbian OS against the latest version online.  Any components of the OS that need to be updated will be downloaded and installed. This step can take some time, like maybe an hour, so go have lunch or whatever. The size of the update downloads can be more than half a gigabyte (512GB), so be aware of that if you have a limited internet connection.
  6. WARNING! A screen saver will blank the screen during the install due to no mouse or keyboard activity. This can make you think the install has crashed.  Just press a key or move the mouse to reactivate the display. You may have to press a key a few times during the updates to reactivate the screen.
  7. More WARNING! If you connected your Pi's power to a TV, the HDMI blanking of the screen saver may cause the TV to turn off, and if your Pi is getting power from the TV, it will also turn off. Turning off your Pi during the updates generally wrecks the OS and may make it unbootable.  The only way to recover is to restart the install from the beginning again. To recover, reboot the system and hold down the shift key at the first splash screen to start NOOBS again and reinstall the OS from scratch. Don't screw it up next time.


Click OK and then click Restart

CONGRATULATIONS on installing the latest version of Raspbian OS. You are now a Linux hyper-guru!  Well not quite, but you've already come a long way.

Now you should have your Raspberry Pi booted to the desktop and connected to your WiFi network.

Setting up VNC

The first thing we should do next is get rid of that keyboard and mouse you've been using and connect to the Pi from your computer using the network.  That way you can use the display, keyboard, and mouse of your computer to control the Pi rather than the ones you have plugged directly into the Pi. 

To do this you will be using VNC. VNC stands for Virtual Network Computing, which is basically a fancy way of saying you're going to share the graphical user interface of your Pi over the network. You can read more about it here:

So now...

  1. Click on the Raspberry icon at the top left of the screen and select Preferences --> Raspberry Pi Configuration. Now go into the Interfaces tab.
  2. Enable VNC and SSH.  We will be using SSH later.
  3. Click OK.

  1. The next thing we need to do is find out the IP address of your Pi so we can connect with VNC.  To do this, hover over the network icon at the top right of the screen. In this case the address is Don't worry about the rest.

  1. Now you'll be able to connect to your Pi's GUI with VNC.  But first you'll need to download and install VNC Viewer. Here's the link
  3. I have to assume you know how to install a program, so I'm not going to post steps for that.  Once you're done, run VNC viewer.
  4. In the line at the top of VNC Viewer, enter the IP address of your Pi and press Enter. A dialog will open asking for your username, which is "pi", and your password, which is the one you changed it to earlier. You can check the Remember password box so you don't have to enter your password every time you connect. When done you can press OK.

  1. You should now see the desktop of your Pi on your computer inside the VNC Viewer window.  All your mouse and keyboard movements within the VNC Viewer window will be mirrored on the HDMI display, and all your mouse and keyboard movements on the USB mouse and keyboard will be mirrored in your VNC Viewer.  Pretty neat huh!

  1. You can now unplug the USB hub, mouse, and keyboard from your Pi, as we will no longer be needing them. You can also disconnect the HDMI cable from the Pi.
  2. Special note: You could have actually turned on VNC as soon as Raspbian booted for the first time and just used VNC from there, and disconnected the keyboard, mouse, and display much earlier.  However I figured if you bothered to dig out that old wired keyboard and mouse from the cupboard or borrow it from a friend just for this, you might as well use them for a while.


If you haven't already turned on IPv6 in your WiFi router, I highly recommend you enter the 21st century and do so. See your router's instruction for how to do this.  In the Google Home app this is easy to find, go to Wi-Fi --> Settings gear icon at top right --> Advanced networking --> IPV6, toggle the switch to the right.

Installing Pi-hole

Now that you've got the operating system installed, it's time to install the ad blocking DNS sinkhole called Pi-hole.

Everything you need to know about Pi-hole can be found at the Pi-hole website

However, the easiest way to install Pi-hole is to open a terminal and install from there.

  1. Click the terminal icon at the top left of your Pi desktop, from within VNC Viewer. This will open a command line interface (CLI) where you can type commands. Linux uses the command line a lot, so you'll need to get used to it a little.

  1. In the command line you're going to type this ridiculous line of text.  This will download and run a script that will install Pi-hole for you.  You can actually copy and paste this into the terminal window by right clicking.

curl -sSL | bash

  1. The terminal window will do something, which will take a while.  Pi-hole is being downloaded and installed onto your Pi.

In the latest version of Pi-hole the above screen will look a little different, it will mention something about non-root privileges.  Don't worry about it.  Press OK on the next couple of blue screeens to move in with the install.  

When given the option to choose an Upstream DNS Server, I recommend selecting Quad9 filtered with DNSSEC. Use the down arrow key to scroll down to Quad9 filtered, DNSSEC and then use the TAB key to select OK and press Enter.

On the next screen, for third party lists, leave everything selected and just press TAB and press Enter.

For protocols, leave IPv4 and IPv6 selected and just press TAB and press Enter again.

In the next screen you will be asked if you want to set the IP address of your Pi as static.

I recommend you select Yes.  Pi-hole always needs to be at the same numerical (IP) address on your network, which is known as a static address.

While it's not strictly best practice to create a static address on your network without reserving it in your router, most routers now days are smart enough to avoid conflicts with static addresses. I know static works just fine on my Google WiFi router.  So if you aren't sure, I suggest you select Yes for a static IP address. 

After setting up your network by pressing "Yes", there will be some other screens to click through. Press OK to continue on each one.

There will be some installing of packages

When finished there will be some notices. Simply press Enter to go past them.

The next section

On the FYI IP conflict screen select OK. See I told ya.

For IPv6 supported select OK.

Be sure to install the web admin interface and the web server.  Press TAB and press Enter on OK to install both

Log queries, TAB, Enter for OK.  Note: the log is a record of all the domain name requests your Pi-hole has received. If you're a privacy nut or paranoid you can turn this off. I've certainly never looked at the logs, but someone might want to if they want to find out what websites you've been visiting. If you'd prefer no one knew, then turn this off.

FTL privacy mode, TAB and press Enter for OK.  Hmm, privacy?

The install will now complete the setup and install all the components of the web server and admin interface. This will take a few minutes.

Some packages will install again.

After the install, the final screen is very important as it shows the IPv4 and IPv6 addresses that you will use for your DNS settings in your router.  It also shows the automatically generated password for the Pi-hole web interface.  Take a photo of this page or copy the values to a Notepad++ file for later use, because these things are very important for the next part of the setup.
Once you're done press Enter for OK

If you want to reconfigure Pi-hole or repair the install, just run the curl command again and select your new options.

curl -sSL | bash

Configuring your router to use Pi-hole as your DNS

In order for Pi-hole to work, your devices need to use it as their Domain Name Server (DNS).  This means that when a device makes a DNS request to find out the numerical address of some domain name such as "", your router will return the address of your Pi-hole. The device will then contact your Pi-hole with the domain name, and the Pi-hole will check to see if the domain name is in its ad blocklist. If the domain name is in the blockist then Pi-hole will return a blank HTML file to the device.  Otherwise it will forward the DNS request to the upstream DNS server you set earlier (Quad9 in this tutorial). 

You don't need to fully understand how DNS works, you just need to set the DNS address in your router to that of your PI-hole.  How to set your router's DNS address depends on your particular router, but it's not difficult.  Use your router's instructions to set the DNS address.  Do not enter secondary DNS addresses because the Pi-hole already has upstream DNS servers set for names that are not in its ad blocklist.  The disadvantage of this upstream DNS setup is that if your Pi-hole goes down then your connection to the internet will also go down. In that case you will need to fix your Pi or temporarily reset your DNS address to one of the defaults, e.g. Google's DNS, or Quad9's DNS,

The two images below show the Google WiFi app on my phone and I'm setting up the IPV4 and IPv6 DNS addresses. Double check that you have entered the correct addresses.  Do not add any secondary DNS addresses other than your Pi-hole's IPv4 and IPv6 addresses.

BE SURE TO CLICK SAVE TO SET THE NEW DNS ADDRESSES. On the the new Google Home app this is a disk icon at top right.

At this point you can now log into the Pi-hole admin web page.  To do this, go to your computer's browser and simply open a browser window and type the address of your Pi-hole and append /admin on the end. Note that the address below uses pi dot hole rather than pi dash hole like the name of Pi-hole.


You can also use the IP address of your Pi-hole, e.g:

This will bring up the Pi-hole dashboard.

I highly recommend you make a bookmark to this page in your browser

The Pi-hole dashboard shows various statistics and menus. Many of these values update their values in real time while you're watching.

The various indicators on the dashboard show:

  • Top left: Pi-hole active, CPU temperature, CPU load values, memory usage. All these update in real time.
  • Green: how many DNS requests your devices have made. This updates in real time
  • Blue: how many DNS requests have been blocked because they are on the blocklist of ad serving domain names. This updates in real time.
  • Yellow: how many percent of DNS requests have been blocked. This updates in real time.
  • Red: how many domain names are on the blocklist.
  • Graph: how many DNS requests and domains blocked over time.
  • Left side: Dashboard, Login, Donate.
  • Hovering the mouse over the Green, Red, and Graph shows extra data.
Try browsing some ad-infested web sites on your devices and watch the numbers change in real time.  If you don't see the numbers change then something may be wrong with your setup. Check that you set your router's DNS addresses correctly. Make sure you didn't set any secondary DNS addresses for IPV4 or IPv6. If that's not the problem then try disconnecting and reconnecting your devices to your network or flushing their DNS cache, e.g. from a DOS window type ipconfig /flushdns

Now that it's all working, the next thing you should do is login to the Pi-hole web interface.  Click the Login button on the left.

You are logging in as user "pi". The password will be the automatically generated one you got at the end of the Pi-hole install.  In my case is was "7MuroVFv".

Logging into the web interface will give you access to more menus and graphs.  

I'll leave it up to you to explore the various menu options. has plenty of documentation for that, so there's no need for me to repeat it. Once you set everything up the device can simply be left to do it's job without any need for maintenance.  The device will automatically update the operating system, Pi-hole, and the blocklist periodically so you don't need to do it manually.

A couple of final settings to change...

Go into Settings and select the DNS tab and check the two IPv6 boxes for your upstream server if they aren't already selected. Quad9 filtered, DNSSEC is the best DNS server to choose. Also check on the right side of this page that "Listen only on interface wlan0" is selected. If you're having trouble with your Pi-hole you can try "Listen on all interfaces". 

Scroll down the DNS Settings page to the Advanced DNS settings.

  1. Uncheck "Never forward non-FQDNs" (Fully Qualified Domain Names).  If you leave this checked then typing a short URL into your browser's URL box like "" will not work, and you will need to type "" instead, which is annoying and unnecessary.
  2. You can leave "Never forward reverse lookup for private IP ranges" checked. Upstream DNS servers are not going to know the names of the devices on your private network. If you want to check how this works, go to a Command window on your PC and lookup the name of a device on your network using its IP address: "nslookup <your device IP>". You should get the name back. If not then change this setting and try again.
  3. Check the box for DNSSEC.  This adds a layer of DNS SECurity to DNS requests. Quad9-filtered accepts the DNSSEC protocol.
  4. Conditional forwarding. This is only used if you aren't using your Pi-hole for DHCP but still want to display proper device names in your Pi-hole dashboard statistics. If you don't set it then devices will be identified only by their IP addresses.  If you turn this on then you need to set your router IP and local domain name.  Typically your router's address is the network address with it's last number set to ".1", e.g. You can also find the address by typing "ipconfig" in a CMD window on your PC and looking for the Default Gateway address. Finding the domain name of your network can be tricky, but the easiest way is to use the CMD window on your PC to find the name of your Default Gateway (i.e. your router) IP address, e.g. "nslookup". In my case my Google WiFi router has the bizarre name of "". I can't even find a setting inside the router to view or change this name.

Once you are done setting your Upstream DNS, the Interface listening behavior, and Advanced DNS settings, Be sure to scroll to the bottom of this page and click Save.

While we're thinking about the Pi-hole admin web page, you need to change that awful automatically generated web admin password, which for me was 7MuroVFv. To do this, go to the terminal window and type "pihole -a -p". Enter your new password and confirm it.

Congratulations!!!  You now have a network-level ad blocker on your network for all your devices and apps!

Check out your Pi-hole dashboard and see how many THOUSANDS of ad requests are blocked. Visit some ad-infested websites and see what numbers you can get. Generally I've found that 20-25% of all my DNS requests are for ads, which will now be blocked!!  A few ads will get through of course, but for the most part you will be ad free!

Check out the FlutterHole app for your phone. It automatically connects to "pi.hole/admin" on your network to show your Pi-hole statistics.

Enjoy your new ad free connection.  

Also, don't be a bragger about your Pi-hole. If everyone had one of these things the internet wouldn't be free and you'd have to pay for most web sites.  Be happy there are other people out there who endure ads so you don't have to. Welcome to our little secret, you non-conformist!! 😄

There is nothing more you need to do to your Pi-hole, it will function just perfectly sitting on your Wi-Fi network and blocking ads.  If you want to however, you can move on to my next blog post linked below, where I show you how to switch from Wi-Fi to a cabled connection, and why that's a good idea. I'll also show you how to turn off unnecessary parts of your Raspberry Pi such as the Wifi, HDMI, and GUI to save electricity, memory, and CPU cycles, so you have the slimmest, most minimalist Pi-hole ever!  I'll also show you how to look at CPU load and other deeper aspects of Linux.

Here is the link to the second post in this two part series, but like I said, you don't need to do these next steps, your Pi-hole will function perfectly well the way it is right now, and if you're not particularly savvy with Linux, then you don't need to go any further.

Thanks for reading. Be sure to subscribe to my blog at the top right of this page for regular updates.

-Dave Bad Person

No comments:

Post a Comment