Back to Details

pihole-dns-troubleshoot-ipv6

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Troubleshoot IPv6 DNS Issues Skill

IPv6 DNS问题排查Skill

Systematic diagnosis and resolution of IPv6 DNS issues that cause clients to bypass local network access and connect via Cloudflare Tunnel with OAuth authentication.
系统性诊断和解决IPv6 DNS问题，这类问题会导致客户端绕过本地网络访问，转而通过带OAuth验证的Cloudflare Tunnel连接。

Quick Start

快速开始

Diagnose IPv6 DNS issue:
bash
undefined
诊断IPv6 DNS问题：
bash
undefined

Check if client is getting IPv6 addresses (should show ONLY IPv4)

检查客户端是否获取IPv6地址（应仅显示IPv4）

getent ahosts ha.temet.ai
getent ahosts ha.temet.ai

Check Pi-hole is blocking IPv6 DNS responses

检查Pi-hole是否阻止IPv6 DNS响应

docker exec pihole nslookup -query=AAAA ha.temet.ai 127.0.0.1
docker exec pihole nslookup -query=AAAA ha.temet.ai 127.0.0.1

Check filter-AAAA is configured

检查filter-AAAA是否已配置

docker exec pihole env | grep FTLCONF_misc_dnsmasq_lines
undefined
docker exec pihole env | grep FTLCONF_misc_dnsmasq_lines
undefined

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
  1. 何时使用此Skill
  2. 此Skill的作用
  3. 操作步骤
    • 3.1 问题理解
    • 3.2 验证IPv6过滤配置
    • 3.3 测试Pi-hole的IPv6阻止功能
    • 3.4 测试客户端DNS解析
    • 3.5 清除客户端DNS缓存
    • 3.6 禁用浏览器DNS-over-HTTPS
    • 3.7 验证修复效果
  4. 支持文件
  5. 预期结果
  6. 前置要求
  7. 需要避免的风险

When to Use This Skill

何时使用此Skill

Explicit Triggers:
  • "Connecting to Cloudflare instead of local"
  • "OAuth prompt on local WiFi"
  • "Services work but require authentication"
  • "IPv6 DNS issue"
  • "Clients prefer IPv6"
Implicit Triggers:
  • 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
Debugging Triggers:
  • "Why am I seeing OAuth on local network?"
  • "Why is local access slow?"
  • "How to disable IPv6 DNS?"
明确触发场景：
  • “连接Cloudflare而非本地网络”
  • “本地WiFi下出现OAuth提示”
  • “服务可用但需验证”
  • “IPv6 DNS问题”
  • “客户端偏好IPv6”
隐含触发场景：
  • 家庭WiFi下服务显示Cloudflare Access OAuth登录界面
  • 初始连接缓慢，验证后可正常使用
  • Chrome显示“重试错误”后连接成功
  • 远程访问服务正常，但本地访问需OAuth验证
调试触发场景：
  • “为什么本地网络会出现OAuth验证？”
  • “为什么本地访问速度慢？”
  • “如何禁用IPv6 DNS？”

What This Skill Does

此Skill的作用

  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
  1. 问题说明 - 详细解释IPv6 DNS导致Cloudflare路由的原理
  2. 配置验证 - 检查FTLCONF_misc_dnsmasq_lines是否设置为filter-AAAA
  3. Pi-hole测试 - 确认Pi-hole阻止IPv6 DNS响应
  4. 客户端测试 - 验证客户端仅接收IPv4地址
  5. 缓存清理 - 指导清理客户端DNS缓存
  6. DoH检查 - 验证浏览器DNS-over-HTTPS已禁用
  7. 修复确认 - 测试本地访问无需OAuth即可正常使用

Instructions

操作步骤

3.1 Understanding the Problem

3.1 问题理解

Root Cause:
Cloudflare DNS has both IPv4 and IPv6 records for tunnel hostnames:
  • IPv4 (A record): 
    192.168.68.136
    (local, from Pi-hole custom DNS)
  • IPv6 (AAAA record): 
    2606:4700:...
    (Cloudflare tunnel, from upstream CNAME)
When clients query for 
*.temet.ai
, they receive both addresses. Modern clients prefer IPv6 → connect to Cloudflare → require OAuth authentication instead of using local network.
Solution:
Configure Pi-hole to block all IPv6 (AAAA) DNS responses using 
filter-AAAA
directive, forcing clients to use IPv4 only.
根本原因：
Cloudflare DNS为隧道主机名同时提供IPv4和IPv6记录：
  • IPv4（A记录）：
    192.168.68.136
    （本地地址，来自Pi-hole自定义DNS）
  • IPv6（AAAA记录）：
    2606:4700:...
    （Cloudflare隧道地址，来自上游CNAME）
当客户端查询
*.temet.ai
时，会收到两个地址。现代客户端偏好IPv6 → 连接Cloudflare → 需OAuth验证，而非使用本地网络。
解决方案：
配置Pi-hole使用
filter-AAAA
指令阻止所有IPv6（AAAA）DNS响应，强制客户端仅使用IPv4。

3.2 Verify IPv6 Filtering Configuration

3.2 验证IPv6过滤配置

Check Pi-hole environment variable:
bash
docker exec pihole env | grep FTLCONF_misc_dnsmasq_lines
Expected output:
FTLCONF_misc_dnsmasq_lines=filter-AAAA
If missing or incorrect:
  1. Edit docker-compose.yml:
bash
nano /home/dawiddutoit/projects/network/docker-compose.yml
  1. Add/update under pihole service environment:
yaml
FTLCONF_misc_dnsmasq_lines: "filter-AAAA"
  1. Restart Pi-hole:
bash
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml up -d pihole
Technical background:
  • Pi-hole v6 uses FTL (not dnsmasq directly)
  • FTLCONF_misc_dnsmasq_lines
    injects dnsmasq config into FTL
  • filter-AAAA
    blocks all IPv6 DNS responses
检查Pi-hole环境变量：
bash
docker exec pihole env | grep FTLCONF_misc_dnsmasq_lines
预期输出：
FTLCONF_misc_dnsmasq_lines=filter-AAAA
若缺失或配置错误：
  1. 编辑docker-compose.yml：
bash
nano /home/dawiddutoit/projects/network/docker-compose.yml
  1. 在pihole服务的environment下添加/更新：
yaml
FTLCONF_misc_dnsmasq_lines: "filter-AAAA"
  1. 重启Pi-hole：
bash
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml up -d pihole
技术背景：
  • Pi-hole v6使用FTL（而非直接使用dnsmasq）
  • FTLCONF_misc_dnsmasq_lines
    将dnsmasq配置注入FTL
  • filter-AAAA
    阻止所有IPv6 DNS响应

3.3 Test Pi-hole IPv6 Blocking

3.3 测试Pi-hole的IPv6阻止功能

Verify Pi-hole blocks IPv6 DNS queries:
bash
undefined
验证Pi-hole阻止IPv6 DNS查询：
bash
undefined

Test single domain (should return "No answer" or no AAAA records)

测试单个域名（应返回“No answer”或无AAAA记录）

docker exec pihole nslookup -query=AAAA ha.temet.ai 127.0.0.1
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

Expected: "No answer" or empty response (no IPv6 addresses returned)

**If IPv6 addresses returned:**
- `filter-AAAA` not working
- Pi-hole FTL hasn't loaded configuration
- Wrong Pi-hole version (needs v6+)
for domain in pihole ha jaeger langfuse sprinkler code webhook; do echo "=== 测试 $domain.temet.ai (AAAA) ===" docker exec pihole nslookup -query=AAAA $domain.temet.ai 127.0.0.1 echo done

预期结果：“No answer”或空响应（无IPv6地址返回）

**若返回IPv6地址：**
- `filter-AAAA`未生效
- Pi-hole FTL未加载配置
- Pi-hole版本错误（需v6+）

3.4 Test Client DNS Resolution

3.4 测试客户端DNS解析

From your computer/device:
bash
undefined
在你的电脑/设备上执行：
bash
undefined

Check what addresses DNS returns (should show ONLY IPv4)

检查DNS返回的地址（应仅显示IPv4）

getent ahosts ha.temet.ai
getent ahosts ha.temet.ai

Or use dig

或使用dig

dig ha.temet.ai A dig ha.temet.ai AAAA

**Expected:**
- `getent ahosts` shows only `192.168.68.136`
- `dig AAAA` returns no AAAA records or NOERROR with empty answer

**If IPv6 addresses appear (2606:4700:...):**
- Client has cached DNS from before filter-AAAA was applied
- Client is using DNS-over-HTTPS (bypassing Pi-hole)
- Client has manual DNS override
dig ha.temet.ai A dig ha.temet.ai AAAA

**预期结果：**
- `getent ahosts`仅显示`192.168.68.136`
- `dig AAAA`返回无AAAA记录或NOERROR且响应为空

**若出现IPv6地址（2606:4700:...）：**
- 客户端缓存了filter-AAAA配置前的DNS记录
- 客户端使用DNS-over-HTTPS（绕过Pi-hole）
- 客户端有手动DNS覆盖配置

3.5 Clear Client DNS Cache

3.5 清除客户端DNS缓存

DNS cache persists for hours. Must clear after configuration changes.
macOS:
bash
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
Linux (systemd-resolved):
bash
sudo systemd-resolve --flush-caches
Linux (no systemd-resolved): Usually no DNS cache, or:
bash
sudo service nscd restart  # If nscd installed
Windows:
bash
ipconfig /flushdns
Mobile devices:
  • iPhone/Android: Restart WiFi connection
  • Or wait 5-60 minutes for cache to expire naturally
After clearing cache: Wait 10-30 seconds, then re-test with 
getent ahosts
.
DNS缓存会留存数小时，配置变更后必须清理。
macOS：
bash
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
Linux（systemd-resolved）：
bash
sudo systemd-resolve --flush-caches
Linux（无systemd-resolved）： 通常无DNS缓存，或执行：
bash
sudo service nscd restart  # 若已安装nscd
Windows：
bash
ipconfig /flushdns
移动设备：
  • iPhone/Android：重启WiFi连接
  • 或等待5-60分钟缓存自然过期
清理缓存后： 等待10-30秒，然后使用
getent ahosts
重新测试。

3.6 Disable Browser DNS-over-HTTPS

3.6 禁用浏览器DNS-over-HTTPS

Modern browsers can bypass local DNS entirely using DNS-over-HTTPS (DoH).
Chrome/Edge:
  1. Settings → Privacy and security → Security
  2. Scroll to "Use secure DNS"
  3. Turn OFF (or select "With your current service provider")
Firefox:
  1. Settings → Privacy & Security
  2. Scroll to "DNS over HTTPS"
  3. Select "Off" or "Default Protection"
Safari:
  • Doesn't use DoH by default (no action needed)
Verification: After disabling DoH, restart browser completely and re-test access.
现代浏览器可通过DNS-over-HTTPS（DoH）完全绕过本地DNS。
Chrome/Edge：
  1. 设置 → 隐私和安全 → 安全
  2. 滚动到“使用安全DNS”
  3. 关闭（或选择“使用当前服务提供商”）
Firefox：
  1. 设置 → 隐私与安全
  2. 滚动到“DNS over HTTPS”
  3. 选择“关闭”或“默认保护”
Safari：
  • 默认不使用DoH（无需操作）
验证： 禁用DoH后，完全重启浏览器并重新测试访问。

3.7 Verify Fix

3.7 验证修复效果

Test local access works without OAuth:
  1. Clear browser cookies for 
    *.cloudflareaccess.com
  2. Open incognito/private window (avoids cached sessions)
  3. Navigate to service: 
    https://ha.temet.ai
Expected:
  • Connects immediately without OAuth prompt
  • Fast connection (<1 second)
  • No redirect to Cloudflare Access
If still seeing OAuth:
  • DNS cache not cleared
  • Browser using DoH
  • Wrong DNS server configured on client
Re-check steps 3.4, 3.5, and 3.6.
测试本地访问无需OAuth即可正常使用：
  1. 清除浏览器中
    *.cloudflareaccess.com
    的Cookie
  2. 打开无痕/隐私窗口（避免缓存会话）
  3. 访问服务： 
    https://ha.temet.ai
预期结果：
  • 立即连接，无OAuth提示
  • 连接速度快（<1秒）
  • 无跳转到Cloudflare Access的情况
若仍显示OAuth：
  • DNS缓存未清理
  • 浏览器使用DoH
  • 客户端配置了错误的DNS服务器
重新检查步骤3.4、3.5和3.6。

Supporting Files

支持文件

FilePurpose
references/reference.md
IPv6 DNS filtering technical details, FTL configuration
examples/examples.md
Example configurations, troubleshooting scenarios
文件用途
references/reference.md
IPv6 DNS过滤技术细节、FTL配置说明
examples/examples.md
示例配置、故障排查场景

Expected Outcomes

预期结果

Success:
  • 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)
Partial Success:
  • Configuration correct but clients have cached DNS (clear cache)
  • Browser using DoH (disable and restart)
Failure Indicators:
  • getent ahosts
    shows IPv6 addresses (2606:4700:...)
  • Services still require OAuth on local WiFi
  • Pi-hole returning IPv6 addresses
成功：
  • Pi-hole阻止所有IPv6 DNS响应
  • 客户端仅接收IPv4地址（192.168.68.136）
  • 本地网络访问无需OAuth验证即可正常使用
  • 连接速度快（<1秒）
部分成功：
  • 配置正确，但客户端存在缓存DNS（需清理缓存）
  • 浏览器使用DoH（需禁用并重启）
失败迹象：
  • getent ahosts
    显示IPv6地址（2606:4700:...）
  • 本地WiFi下服务仍需OAuth验证
  • Pi-hole返回IPv6地址

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
  • 使用FTL DNS服务器的Pi-hole v6+
  • 运行Pi-hole容器的Docker环境
  • 可访问FTLCONF_misc_dnsmasq_lines环境变量
  • 可访问客户端设备以清理DNS缓存

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+)
  • 不要在网络层面禁用IPv6（会影响其他服务）
  • 不要删除Cloudflare中的IPv6 DNS记录（远程访问需要）
  • 不要跳过清理客户端DNS缓存（变更不会生效）
  • 不要忘记检查浏览器DNS-over-HTTPS设置
  • 不要在同一浏览器标签页测试（使用无痕窗口）
  • 不要期望即时生效（DNS缓存可留存5-60分钟）
  • 不要使用Pi-hole v5或更早版本（filter-AAAA需要v6+的FTL）

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
  • IPv6过滤是全网络生效的（影响所有客户端）
  • Cloudflare tunnel仍使用IPv6进行远程访问（此为正常配置）
  • filter-AAAA仅阻止IPv6 DNS响应，不影响IPv6连通性
  • 客户端缓存留存时间不同：Windows为5分钟，移动设备为60分钟
  • DoH会绕过所有本地DNS设置（必须禁用）
  • 配置在Pi-hole重启后仍保持持久（存储在FTL配置中）
  • 可使用domains.toml进行自动化DNS管理，但IPv6过滤需手动配置