Local DNS records in Pi-hole allow you to create custom hostname-to-IP address mappings for your local network. Let me explain their key uses and benefits:

Main Uses of Local DNS Records

1. Custom Device Names

   • Map friendly names to local IP addresses (e.g., printer.local → 192.168.1.50)
   • Access devices by name instead of remembering IP addresses

2. Internal Services

   • Create shortcuts to local services (e.g., nas.home → 192.168.1.100)
   • Access internal websites using custom domains

3. Development Testing

   • Point domains to local development servers
   • Test websites locally before deployment

Common Examples

# Basic local DNS record examples
printer.local     → 192.168.1.50
nas.home          → 192.168.1.100
homeserver.local  → 192.168.1.150
dashboard.local   → 192.168.1.200

Benefits

1. Simplified Access

   • Use memorable names instead of IP addresses
   • Easier sharing of network resources

2. Network Organization

   • Better organization of network devices
   • Simplified network documentation

3. Stability

   • Services remain accessible even if IP addresses change
   • Works offline, independent of internet connectivity

4. Security

   • Keep internal services private
   • Avoid exposing internal IPs to external DNS servers

Setting Up Local DNS Records in Pi-hole

Method 1: Using Pi-hole Web Interface

1. Access Pi-hole admin interface (http://pi.hole/admin)
2. Navigate to "Local DNS" → "DNS Records"
3. Add new entries:
   • Domain: Enter the hostname (e.g., printer.local)
   • IP Address: Enter the corresponding IP (e.g., 192.168.1.50)
   • Click "Add"

Method 2: Manual Configuration File

1. SSH into your Pi-hole

2. Edit the custom DNS configuration file:

   sudo nano /etc/dnsmasq.d/02-custom.conf
   

3. Add entries in this format:

   address=/hostname.local/192.168.1.50
   address=/another.local/192.168.1.51
   

4. Save the file and restart DNS service:

   sudo pihole restartdns
   

Example Configurations

Basic Records

# Network devices
address=/printer.local/192.168.1.50
address=/nas.local/192.168.1.100
address=/router.local/192.168.1.1

# Internal services
address=/plex.home/192.168.1.150
address=/homeassistant.local/192.168.1.160
address=/dashboard.local/192.168.1.170

Advanced Configurations

CNAME Records

# Point multiple domains to same IP
cname=media.local,plex.home
cname=movies.local,plex.home

Wildcard Domains

# Match all subdomains
address=/*.test.local/192.168.1.200

Verification and Testing

1. Test DNS resolution:

   ping printer.local
   nslookup nas.local
   

2. Check Pi-hole logs:

   pihole -t
   

Troubleshooting

Common Issues

1. Name Not Resolving

   • Verify DNS record exists
   • Check spelling and format
   • Ensure Pi-hole is primary DNS server

2. Conflicts

   • Check for duplicate entries
   • Verify no conflicts with external DNS

3. Cache Issues

   • Clear Pi-hole cache: bash pihole restartdns flush
   • Clear device DNS cache

Best Practices

1. Use Consistent Naming

   • Choose a naming convention (.local, .home, etc.)
   • Document all custom records

2. Regular Maintenance

   • Review and update records regularly
   • Remove obsolete entries
   • Backup configuration

3. Security Considerations

   • Use internal-only TLDs (.local, .home)
   • Avoid using public domain names
   • Document access methods

Backup and Recovery

1. Backup custom DNS configurations:

   sudo cp /etc/dnsmasq.d/02-custom.conf /backup/
   

2. Export Pi-hole settings:

   • Use teleporter feature in web interface
   • Save configuration files