DNS Configuration with Pi-hole

Pi-hole Installation and Setup

Docker Compose Configuration

Our MCT Services Pi-hole configuration:

pihole:
  image: pihole/pihole:2024.01.0
  container_name: pihole
  restart: unless-stopped
  networks:
    mct_macvlan:
      ipv4_address: 10.44.10.53
    mct_public: {}  # For Traefik routing
  environment:
    TZ: Pacific/Honolulu
    WEBPASSWORD: admin
    PIHOLE_DNS_: "1.1.1.1;8.8.8.8"
    DNSMASQ_LISTENING: local
    WEB_PORT: 80
  volumes:
    - pihole_data:/etc/pihole
    - pihole_dnsmasq:/etc/dnsmasq.d
  healthcheck:
    test: ["CMD", "dig", "+norecurse", "+retry=0", "@127.0.0.1", "pi.hole"]
    interval: 30s
    timeout: 10s
    retries: 3

Key Configuration Parameters

Network Configuration
  • mct_macvlan - Direct network access
  • ipv4_address: 10.44.10.53 - Static IP assignment
  • DNSMASQ_LISTENING: local - Listen on local interfaces only
DNS Upstream
  • PIHOLE_DNS_: "1.1.1.1;8.8.8.8" - Cloudflare and Google DNS
  • Alternative: 9.9.9.9;149.112.112.112 - Quad9
  • Privacy option: 127.0.0.1#5053 - Local Unbound

MacVLAN Network Setup

Network Creation

# Create MacVLAN network
docker network create -d macvlan 
  --subnet=10.44.10.0/24 
  --gateway=10.44.10.1 
  --ip-range=10.44.10.50/28 
  -o parent=eth0 
  mct_macvlan

Network Parameters

  • --subnet - Match your physical network
  • --gateway - Your router IP
  • --ip-range - Reserved range for containers
  • -o parent=eth0 - Physical interface name

Pi-hole Web Interface

Initial Setup

  1. Access Pi-hole at http://10.44.10.53/admin
  2. Login with configured password
  3. Complete initial setup wizard
  4. Configure upstream DNS servers

Dashboard Overview

  • Total Queries: DNS requests processed
  • Queries Blocked: Ads and malware blocked
  • Percent Blocked: Blocking effectiveness
  • Domains on Blocklist: Number of blocked domains

Local DNS Records Configuration

Method 1: Pi-hole Web Interface

Navigate to Local DNS → DNS Records:

  1. Click "Add a new domain/IP combination"
  2. Enter domain: metube.mct.lan
  3. Enter IP: 10.44.10.100
  4. Click "Add"

Method 2: Custom DNS File

Create /etc/dnsmasq.d/02-mct-local.conf:

# MCT Services Local DNS
address=/hub.mct.lan/10.44.10.100
address=/auth.mct.lan/10.44.10.100
address=/metube.mct.lan/10.44.10.100
address=/stash.mct.lan/10.44.10.100
address=/dns.mct.lan/10.44.10.53
address=/edge.mct.lan/10.44.10.100

# Wildcard for all mct.lan subdomains
address=/.mct.lan/10.44.10.100

Method 3: Docker Volume Mount

Mount custom configuration:

volumes:
  - ./pihole/custom.conf:/etc/dnsmasq.d/02-custom.conf:ro

Advanced DNS Configuration

Conditional Forwarding

Forward specific domains to other DNS servers:

# Forward company.local to internal DNS
server=/company.local/192.168.1.10

# Forward reverse DNS for local network
server=/10.44.10.in-addr.arpa/10.44.10.1

CNAME Records

Create aliases for services:

# Aliases for main services
cname=www.mct.lan,hub.mct.lan
cname=admin.mct.lan,hub.mct.lan
cname=dashboard.mct.lan,hub.mct.lan

MX Records

Configure mail server records:

# Mail server configuration
mx-host=mct.lan,mail.mct.lan,10
mx-host=mct.lan,backup-mail.mct.lan,20

TXT Records

Add TXT records for verification:

# SPF record
txt-record=mct.lan,"v=spf1 mx ~all"

# Domain verification
txt-record=_verification.mct.lan,"verification-token-here"

Blocklist Management

Default Blocklists

Pi-hole comes with curated blocklists:

  • StevenBlack's Unified hosts file
  • Malware Domain List
  • Cameleon
  • Disconnect.me Tracking

Custom Blocklists

Add additional blocklists in Group Management → Adlists:

# Popular additional lists
https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
https://someonewhocares.org/hosts/zero/hosts
https://raw.githubusercontent.com/AdguardTeam/AdguardFilters/master/BaseFilter/sections/adservers.txt

Whitelist Management

Allow specific domains that might be blocked:

  • Navigate to Domains → Whitelist
  • Add domains that should never be blocked
  • Use wildcards: *.example.com

Query Logging and Analytics

Query Log

Monitor DNS queries in real-time:

  • View all DNS requests
  • See blocked vs allowed queries
  • Identify problematic domains
  • Track client activity

Long-term Data

Analyze trends over time:

  • Queries over time graphs
  • Top domains and clients
  • Blocked domain statistics
  • Query type distribution

Privacy Considerations

Configure privacy settings:

  • Query logging level
  • Data retention period
  • Client anonymization
  • Statistics granularity

Client Configuration

Router DHCP Settings

Configure your router to use Pi-hole:

  1. Access router admin interface
  2. Navigate to DHCP settings
  3. Set Primary DNS: 10.44.10.53
  4. Set Secondary DNS: 1.1.1.1 (fallback)
  5. Save and restart DHCP service

Manual Client Configuration

For devices with static IP:

Linux:

# Edit /etc/systemd/resolved.conf
[Resolve]
DNS=10.44.10.53
FallbackDNS=1.1.1.1
Domains=mct.lan

Windows:

# Network adapter properties
Primary DNS: 10.44.10.53
Secondary DNS: 1.1.1.1
DNS suffix: mct.lan

macOS:

# System Preferences → Network → Advanced → DNS
DNS Servers: 10.44.10.53, 1.1.1.1
Search Domains: mct.lan

Testing DNS Configuration

Command Line Testing

# Test local domain resolution
nslookup metube.mct.lan 10.44.10.53
dig @10.44.10.53 metube.mct.lan

# Test external domain resolution
nslookup google.com 10.44.10.53
dig @10.44.10.53 google.com

# Test reverse DNS
nslookup 10.44.10.100 10.44.10.53

Browser Testing

  1. Clear browser DNS cache
  2. Navigate to http://metube.mct.lan
  3. Verify resolution without hosts file entries
  4. Test from different devices on network

Mobile Device Testing

  1. Connect mobile device to WiFi
  2. Verify DNS settings in WiFi properties
  3. Test service access from mobile browser
  4. Check Pi-hole query logs for mobile requests

Troubleshooting DNS Issues

Common Problems

DNS Not Resolving
  • Check Pi-hole container status
  • Verify network connectivity
  • Check DNS configuration syntax
  • Restart dnsmasq service
Slow DNS Resolution
  • Check upstream DNS performance
  • Monitor Pi-hole resource usage
  • Optimize blocklist size
  • Consider DNS caching
Blocked Legitimate Sites
  • Check query logs for blocked domains
  • Add domains to whitelist
  • Review blocklist sources
  • Adjust blocking sensitivity

Debugging Commands

# Check Pi-hole status
docker exec pihole pihole status

# Test DNS resolution
docker exec pihole nslookup metube.mct.lan localhost

# Check dnsmasq configuration
docker exec pihole cat /etc/dnsmasq.d/02-custom.conf

# View Pi-hole logs
docker logs pihole --tail 100

# Restart DNS service
docker exec pihole pihole restartdns

Performance Optimization

Caching Configuration

# Increase cache size
cache-size=10000

# Set cache TTL
local-ttl=300
neg-ttl=3600

Resource Monitoring

  • Monitor container memory usage
  • Check DNS query response times
  • Optimize blocklist management
  • Consider Pi-hole clustering

Next Steps

In the next lesson, we will explore network integration strategies and how to make Pi-hole the authoritative DNS server for your entire network.

Last modified: Thursday, 6 November 2025, 9:03 AM