Pi-hole can act as your local DNS server, and one of its lesser-known but incredibly useful features is the ability to create CNAME records for your local network. This lets you assign easy-to-remember aliases to specific IP addresses within your network, making it feel like you have your own internal domain name system.
Imagine you have a server at 192.168.1.10 that hosts your Plex media server. Instead of typing 192.168.1.10 into every device, you could create a CNAME record so you can just type plex.local. Here’s how it works in practice.
First, let’s see Pi-hole in action. We’ll set up a CNAME for a hypothetical Raspberry Pi running a web server.
Scenario:
- Pi-hole IP:
192.168.1.2 - Raspberry Pi Web Server IP:
192.168.1.15 - Desired Alias:
my-webserver.local
Step 1: Access Pi-hole’s Web Interface
Log in to your Pi-hole’s web admin panel (e.g., http://192.168.1.2/admin).
Step 2: Navigate to Local DNS Records
Go to Local DNS in the left-hand menu.
Step 3: Add a New Record
You’ll see two fields: "Domain" and "IP Address."
- Domain: Enter
my-webserver.local - IP Address: Enter
192.168.1.15
Click the Add button.
Step 4: Verify the Record
The new record will appear in the table below.
Step 5: Test from a Client Device
On any device configured to use Pi-hole as its DNS server (e.g., your laptop, phone), open a command prompt or terminal and try to ping the new alias:
ping my-webserver.local
You should see output similar to this, indicating that my-webserver.local resolves to 192.168.1.15:
PING my-webserver.local (192.168.1.15): 56 data bytes
64 bytes from 192.168.1.15: icmp_seq=0 ttl=64 time=1.234 ms
64 bytes from 192.168.1.15: icmp_seq=1 ttl=64 time=0.987 ms
...
Now, if you have a web server running on 192.168.1.15, you can access it by navigating to http://my-webserver.local in your browser.
The Mental Model: How Pi-hole Handles Local DNS
Pi-hole’s core function is to intercept DNS queries and either block them (if they match a blocklist) or forward them to an upstream DNS server. When you add a local DNS record, you’re telling Pi-hole to handle certain queries before it even considers forwarding them.
- Query Interception: A device on your network asks Pi-hole for the IP address of
my-webserver.local. - Local Record Check: Pi-hole checks its internal list of "Local DNS Records." It finds a match for
my-webserver.local. - Direct Resolution: Instead of querying Google DNS, Cloudflare, or any other upstream server, Pi-hole immediately returns the IP address you configured:
192.168.1.15. - Client Connection: The device then uses this IP address to connect directly to your Raspberry Pi.
This mechanism is fundamentally different from how Pi-hole handles external domains. For external domains, it’s a gatekeeper and forwarder; for local domains, it’s the authoritative source.
Why is this useful?
- Memorability:
plex.localis much easier to remember than192.168.1.10. - Flexibility: If you change the IP address of a device (e.g., due to DHCP lease changes), you only need to update the IP address in one place in Pi-hole, not on every device that accesses it.
- Internal Naming: You can create a consistent naming scheme for all your local devices, making your network feel more organized.
The Exact Levers You Control:
- Domain Name: This is the alias you want to use (e.g.,
nas.home,printer.lan,camera.local). Pi-hole generally recommends using.localfor these, as it’s a common convention for local network devices and less likely to conflict with real internet domains. - IP Address: This is the actual IP address of the device on your local network that the domain name should resolve to.
The "Domain" field in Pi-hole’s Local DNS interface is where you input the desired alias. The "IP Address" field is where you put the actual IP address of the target device. When you add a record, Pi-hole stores this mapping in its configuration, typically in a file like /etc/pihole/custom.list or within its database, depending on your Pi-hole version and configuration.
One thing most people don’t realize is that Pi-hole’s local DNS resolution takes precedence over any DNSSEC validation it might perform for external domains. If you have my-webserver.local configured locally and an external DNS provider somehow had a record for my-webserver.local (highly unlikely for a .local domain, but conceptually possible for other TLDs), Pi-hole would always return your local IP. This absolute precedence ensures your internal network aliases are always the source of truth for your local network.
After setting up your local DNS aliases, the next logical step is to explore Pi-hole’s conditional forwarding feature, which can help resolve hostnames for devices that aren’t directly configured in Pi-hole’s local DNS records.