The most surprising thing about custom DNS records in Pi-hole is that they aren’t just for mapping external hostnames to internal IPs; they’re primarily for mapping internal hostnames to internal IPs, effectively turning your Pi-hole into your own mini-DNS server for your local network.
Imagine you have a server in your house running a web service on port 80. You want to access it not by typing 192.168.1.100 into your browser, but by typing myserver.local. Pi-hole can make this happen.
Here’s a Pi-hole setup with a custom A record for nas.local pointing to the IP address 192.168.1.50:
# SSH into your Pi-hole
ssh pihole@pi.hole
# Add the A record using pihole -a -add
# Format: pihole -a -add <domain> <ip_address>
pihole -a -add nas.local 192.168.1.50
After running this command, Pi-hole will confirm the addition:
Added 'nas.local' (A) to the long-term database.
Now, any device on your network configured to use Pi-hole for DNS will be able to resolve nas.local to 192.168.1.50. You can test this from another client on your network:
# On a client machine (Linux/macOS)
dig nas.local
The output will show:
; <<>> DiG 9.16.1-Ubuntu <<>> nas.local
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 12345
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;nas.local. IN A
;; ANSWER SECTION:
nas.local. 300 IN A 192.168.1.50
;; Query time: 1 msec
;; SERVER: 192.168.1.2#53(192.168.1.2)
;; WHEN: Mon Nov 20 10:00:00 PST 2023
;; MSG SIZE rcvd: 49
This works because Pi-hole, when it receives a DNS query for nas.local, checks its own list of "Custom DNS Records" before it forwards the query to your upstream DNS server (like Google DNS or Cloudflare DNS). If it finds a match, it answers the query directly from its own records. If it doesn’t find a match, it proceeds with its normal DNS resolution process.
You can view your custom DNS records in the Pi-hole web interface under "Local DNS" -> "DNS Records". This is where you can also manually add, edit, or delete records if you prefer not to use the command line.
The primary use case here is for devices on your local network that don’t have their own DHCP server (or whose DHCP server you don’t control) to assign hostnames. By configuring these devices to use Pi-hole as their DNS server, you can assign them friendly, memorable names that are resolvable only within your network. This is incredibly useful for home servers, network-attached storage (NAS) devices, development machines, or any other local service you want to access easily.
The pihole -a -add command is a shortcut for adding A records. You can also add other record types like CNAME, MX, TXT, and more using the pihole -a -add command with the appropriate type flag. For example, to add a CNAME record:
pihole -a -add www.nas.local nas.local CNAME
This would make www.nas.local also resolve to 192.168.1.50 via nas.local.
The magic of Pi-hole’s custom DNS is that it operates at the DNS layer, meaning you don’t need to configure anything on the individual client devices beyond telling them to use Pi-hole for DNS. This centralizes your local name resolution, making it much easier to manage.
When you add a local A record, Pi-hole stores it in a file, typically located at /etc/pihole/custom.list. This file is read by dnsmasq, the DNS forwarder that Pi-hole uses, to handle local name lookups. The pihole -a -add command simply appends the new record to this file and then signals dnsmasq to reload its configuration.
You can also add PTR records (reverse DNS lookups) using pihole -a -add <ip_address> <domain> PTR. This allows you to resolve an IP address back to a hostname within your local network, which can be useful for some network tools or logging.
The next step is to explore how Pi-hole handles wildcard DNS entries for local domains.