Using PiHole for local DNS

PiHole is an open source application that was developed to help block ads and unwanted sites. These sites are often blocked at the DNS query level. But what is DNS? DNS or Domain Name System is like a phone book for the internet, you don't necessarily know a business phone number, but you know the business name. DNS works in a similar fashion, we may not know the IP to google.com but we do know that it is its website. DNS was developed to help everyone using the internet resolve IP address with an easy to remember name. Just like Google's IP 8.8.8.8 translates to dns.google.

On this blog post, we are going to discuss what PiHole is, what local DNS is, how to install it and how to use pihole to help us resolve the complexity of setting up our computer's host file to resolve DNS queries.

What is PiHole?

PiHole is an open source ad sinkhole that leverages DNS to help block ads and unwanted sites. By default, it comes with a list of websites that it blocks including some ads web servers but you can always find plenty of helpful posts and repositories shared in Github to help prevent more unwanted sites. Now keep in mind that this is not always helpful as you will find a lot of false positives and should be handled with care. Besides, it is not my intension to discuss that on this post.

PiHole can be installed on most Linux based OS as well as on Docker containers, there are some OS that it can be installed on but there are little to no support on those. On this post, we are going to go over the process of installing it using Docker.

Now that we know what PiHole is, what is local DNS?

DNS can be compose of the following device.domain.tld. the domain is a name you're giving to your home or entity, example, abetech. The tld or top level domain, it is the last portion of URLs and helps form the full domain, these are but not limited to, .com, .net, .us, .org, .me, .lan, .arp just to name a few.

Local DNS is nothing more than a way to resolve our devices by a memorable name. What do I mean by this? say you have a laptop called AbesLaptop and you are trying to find it in your network using this name. On your router, you will be able to see the IP and not the device name as above but if you use a local DNS you may create a record which can then resolve your name query. As an example 192.168.1.5 can be mapped to resolve for AbesLaptop.

How is local DNS handled?

Local DNS is normally handled by your home router or firewall. You will enter an IP address of where DNS is being handled on the DNS server information. On this field it is often prefilled by your service provider DNS IP which only resolves external DNS to help you connect to the internet.

This information only lives in your home router and some times you want to setup something similar, say a Plex media server or a Minecraft server and you don't necessarily want to access it from its IP. It has happened to me that I go 3-5 days and weeks at time without accessing something and I forget that service IP. That's when local DNS comes into place.

You can setup local DNS on a per device basis by modifying the host files. For Windows this is located on C:\Windows\System32\Drivers\etc\hosts with no file type. On Mac and Linux, this would be located at /etc/hosts . This is what it would look like on my laptop:

In order to add a new entry for plex, I would modify this file and add a line at the end as follows:

192.168.60.223    web.abetech.arp

This entry will direct me to this IP address 192.168.60.223 every time I type web.abetech.arp on my browser or even on the terminal.

This is one way of setting up local DNS but what if you have more than one computer? What is the DNS name change for more than one server? This process can be cumbersome and not ideal and having a PiHole that can do DNS is more of a process that you'd rather want to take advantage of.

How do I install PiHole?

There are multiple ways of installing PiHole. The easiest way is using their automated script which pulls their Github repo then install using their basic setup script. Then there is a Docker container install using a basic docker line or a docker compose file. I personally use a Proxmox container (CT) then use the automated install script, but today we are taking a look at the docker compose file.

Here is their Docker Compose file at the moment of this writing:

# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      # DNS Ports
      - "53:53/tcp"
      - "53:53/udp"
      # Default HTTP Port
      - "80:80/tcp"
      # Default HTTPs Port. FTL will generate a self-signed certificate
      - "443:443/tcp"

    environment:
      TZ: 'Europe/London'
      FTLCONF_webserver_api_password: 'correct horse battery staple'
      FTLCONF_dns_listeningMode: 'all'
    # Volumes store your data between container upgrades
    volumes:
      # For persisting Pi-hole's databases and common configuration file
      - './etc-pihole:/etc/pihole'
    restart: unless-stopped

On this Docker compose, we are specifying the container to use the DNS Port 53 TCP and UDP as well as the required ports for the web management interface, port 80 and 443. We are setting up the time zone using the TZ environment variable and the web password using the FTPCONF_webserver_api_password for which I highly recommend you use your own. We also set the listening mode to all as we want to make sure PiHole listens from all origins to solve your DNS records.

Please visit this Wikipedia article that explains how PiHole expects the time zone entry. Additionally, you can read more on how PiHole uses the listening mode here.

Once this has been configured, you can set the IP of the host machine for your container as your preferred DNS Server on your PC or on the router to apply to all.

How do I setup local DNS record within PiHole?

To setup DNS records within PiHole it is as simple as accessing the management web interface and clicking on "Local DNS" from the left panel. Here you can configure either an A record, which is the normal record we discussed above or a CNAME record which is an alias for an A record. From there, you can fill up the domain as in device.domain.tld, in our case above, web.abetech.arp and assign the IP of the device that contains that web server.

Alright, I now have a better understanding of how to set records but how do I set this on all devices?

To make your devices be able to read the DNS entries, you must set the IP of your PiHole on your router as the DNS resolver or DNS entry. This will permit that all of the devices on your network read from it.

Important note, if the PiHole machine turns off or you have a power outage and the PiHole does not turn back on, all of your devices wont be able to access the internet and this is the importance of having a backup DNS on your records.

As an example, on the Unifi Dream Machine, the DNS records can be updated by going to

Settings > Networks > Select Your Network

After selecting your network, scroll to the bottom and open the Advanced DHCP Service Management options. From there, you can uncheck the DNS Server Auto option and you will be presented with the options to set your DNS

Key take aways

PiHole is a solid but lightweight tool that helps block ads at the DNS level. This can help speed up your internet browsing experience by minimizing the domains a page needs to load. This also prevent or minimizes website trackers which are built into the ads. PiHole can also be used for local DNS and for someone with a homelab, having a local DNS is imperative, because why bother remembering that many IP addresses when you can use a service name?

On this article we discussed what is PiHole, how it is used, how to install it and how to set it so that all of your devices at home can benefit from having a local DNS resolver.

Now the final question is, how are you using it and which blocklists are you using?