Troubleshoot IPv6 DNS Issues Skill

Quick Start

# Check if client is getting IPv6 addresses (should show ONLY IPv4)
getent ahosts ha.temet.ai

# Check Pi-hole is blocking IPv6 DNS responses
docker exec pihole nslookup -query=AAAA ha.temet.ai 127.0.0.1

# Check filter-AAAA is configured
docker exec pihole env | grep FTLCONF_misc_dnsmasq_lines

Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Instructions
   • 3.1 Understanding the Problem
   • 3.2 Verify IPv6 Filtering Configuration
   • 3.3 Test Pi-hole IPv6 Blocking
   • 3.4 Test Client DNS Resolution
   • 3.5 Clear Client DNS Cache
   • 3.6 Disable Browser DNS-over-HTTPS
   • 3.7 Verify Fix
4. Supporting Files
5. Expected Outcomes
6. Requirements
7. Red Flags to Avoid

When to Use This Skill

• "Connecting to Cloudflare instead of local"
• "OAuth prompt on local WiFi"
• "Services work but require authentication"
• "IPv6 DNS issue"
• "Clients prefer IPv6"

• Services show Cloudflare Access OAuth login on home WiFi
• Slow initial connection, then works after authentication
• Chrome shows "error with retry" then connects
• Services work remotely but require OAuth locally

• "Why am I seeing OAuth on local network?"
• "Why is local access slow?"
• "How to disable IPv6 DNS?"

What This Skill Does

1. Explains Problem - Details how IPv6 DNS causes Cloudflare routing
2. Verifies Config - Checks FTLCONF_misc_dnsmasq_lines is set to filter-AAAA
3. Tests Pi-hole - Confirms Pi-hole blocks IPv6 DNS responses
4. Tests Client - Verifies client only receives IPv4 addresses
5. Clears Cache - Guides client-side DNS cache clearing
6. Checks DoH - Verifies browser DNS-over-HTTPS is disabled
7. Confirms Fix - Tests local access works without OAuth

Instructions

3.1 Understanding the Problem

• IPv4 (A record):

  192.168.68.136

  (local, from Pi-hole custom DNS)
• IPv6 (AAAA record):

  2606:4700:...

  (Cloudflare tunnel, from upstream CNAME)

*.temet.ai

filter-AAAA

3.2 Verify IPv6 Filtering Configuration

docker exec pihole env | grep FTLCONF_misc_dnsmasq_lines

FTLCONF_misc_dnsmasq_lines=filter-AAAA

1. Edit docker-compose.yml:

nano /home/dawiddutoit/projects/network/docker-compose.yml

1. Add/update under pihole service environment:

FTLCONF_misc_dnsmasq_lines: "filter-AAAA"

1. Restart Pi-hole:

docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml up -d pihole

• Pi-hole v6 uses FTL (not dnsmasq directly)

• FTLCONF_misc_dnsmasq_lines

  injects dnsmasq config into FTL

• filter-AAAA

  blocks all IPv6 DNS responses

3.3 Test Pi-hole IPv6 Blocking

# Test single domain (should return "No answer" or no AAAA records)
docker exec pihole nslookup -query=AAAA ha.temet.ai 127.0.0.1

# Test all domains
for domain in pihole ha jaeger langfuse sprinkler code webhook; do
  echo "=== Testing $domain.temet.ai (AAAA) ==="
  docker exec pihole nslookup -query=AAAA $domain.temet.ai 127.0.0.1
  echo
done

• filter-AAAA

  not working
• Pi-hole FTL hasn't loaded configuration
• Wrong Pi-hole version (needs v6+)

3.4 Test Client DNS Resolution

# Check what addresses DNS returns (should show ONLY IPv4)
getent ahosts ha.temet.ai

# Or use dig
dig ha.temet.ai A
dig ha.temet.ai AAAA

• getent ahosts

  shows only

  192.168.68.136

• dig AAAA

  returns no AAAA records or NOERROR with empty answer

• Client has cached DNS from before filter-AAAA was applied
• Client is using DNS-over-HTTPS (bypassing Pi-hole)
• Client has manual DNS override

3.5 Clear Client DNS Cache

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

sudo systemd-resolve --flush-caches

sudo service nscd restart  # If nscd installed

ipconfig /flushdns

• iPhone/Android: Restart WiFi connection
• Or wait 5-60 minutes for cache to expire naturally

getent ahosts

3.6 Disable Browser DNS-over-HTTPS

1. Settings → Privacy and security → Security
2. Scroll to "Use secure DNS"
3. Turn OFF (or select "With your current service provider")

1. Settings → Privacy & Security
2. Scroll to "DNS over HTTPS"
3. Select "Off" or "Default Protection"

• Doesn't use DoH by default (no action needed)

3.7 Verify Fix

1. Clear browser cookies for

   *.cloudflareaccess.com

2. Open incognito/private window (avoids cached sessions)
3. Navigate to service:

   https://ha.temet.ai

• Connects immediately without OAuth prompt
• Fast connection (<1 second)
• No redirect to Cloudflare Access

• DNS cache not cleared
• Browser using DoH
• Wrong DNS server configured on client

Supporting Files

references/reference.md

examples/examples.md

Expected Outcomes

• Pi-hole blocks all IPv6 DNS responses
• Clients receive only IPv4 addresses (192.168.68.136)
• Local network access works without OAuth authentication
• Fast connection times (<1 second)

• Configuration correct but clients have cached DNS (clear cache)
• Browser using DoH (disable and restart)

• getent ahosts

  shows IPv6 addresses (2606:4700:...)
• Services still require OAuth on local WiFi
• Pi-hole returning IPv6 addresses

Requirements

• Pi-hole v6+ using FTL DNS server
• Docker running with Pi-hole container
• FTLCONF_misc_dnsmasq_lines environment variable access
• Client device access to clear DNS cache

Red Flags to Avoid

• Do not disable IPv6 at network level (breaks other services)
• Do not delete IPv6 DNS records in Cloudflare (needed for remote access)
• Do not skip clearing client DNS cache (changes won't take effect)
• Do not forget to check browser DNS-over-HTTPS settings
• Do not test in same browser tab (use incognito window)
• Do not expect instant propagation (DNS cache can persist 5-60 minutes)
• Do not use Pi-hole v5 or earlier (filter-AAAA requires FTL in v6+)

Notes

• IPv6 filtering is network-wide (affects all clients)
• Cloudflare tunnel still uses IPv6 for remote access (this is correct)
• filter-AAAA only blocks IPv6 DNS responses, not IPv6 connectivity
• Client cache persistence varies: 5 minutes (Windows) to 60 minutes (mobile)
• DoH bypasses ALL local DNS settings (must be disabled)
• Configuration is persistent across Pi-hole restarts (stored in FTL config)
• Use domains.toml for automated DNS management, but IPv6 filtering is manual