Back to Details

pihole-dns-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pi-hole DNS Setup Skill

Pi-hole DNS配置技能

Configure Pi-hole local DNS records for local network resolution of temet.ai domains.
配置Pi-hole本地DNS记录，实现temet.ai域名的本地网络解析。

Quick Start

快速开始

Run automated DNS setup from domains.toml:
bash
cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply
Or manually add a single DNS record:
bash
undefined
从domains.toml运行自动化DNS搭建：
bash
cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply
或手动添加单个DNS记录：
bash
undefined

Get Pi IP

获取树莓派IP

PI_IP=$(hostname -I | awk '{print $1}')
PI_IP=$(hostname -I | awk '{print $1}')

Test DNS resolution

测试DNS解析

dig @localhost pihole.temet.ai +short
undefined
dig @localhost pihole.temet.ai +short
undefined

Table of Contents

目录

  1. When to Use This Skill
  2. What This Skill Does
  3. Instructions
    • 3.1 Detect Pi IP Address
    • 3.2 Get Domains from Configuration
    • 3.3 Apply DNS Changes
    • 3.4 Verify DNS Resolution
    • 3.5 Router DNS Reminder
  4. Supporting Files
  5. Expected Outcomes
  6. Requirements
  7. Red Flags to Avoid
  1. 何时使用该技能
  2. 该技能的作用
  3. 操作步骤
    • 3.1 检测树莓派IP地址
    • 3.2 从配置文件获取域名
    • 3.3 应用DNS变更
    • 3.4 验证DNS解析
    • 3.5 路由器DNS配置提醒
  4. 支持文件
  5. 预期结果
  6. 环境要求
  7. 注意事项

When to Use This Skill

何时使用该技能

Explicit Triggers:
  • "Set up Pi-hole DNS"
  • "Configure local DNS"
  • "Add DNS record for [domain]"
  • "Set up DNS entries"
  • "Make [service].temet.ai resolve locally"
Implicit Triggers:
  • After adding a new service to domains.toml
  • When local resolution fails for temet.ai domains
  • Setting up a fresh Pi-hole installation
  • Migrating services to new IP addresses
Debugging Triggers:
  • "DNS not resolving"
  • "Can't access [service].temet.ai on local network"
  • "dig returns wrong IP"
  • "Works remotely but not locally"
明确触发场景：
  • “搭建Pi-hole DNS”
  • “配置本地DNS”
  • “为[域名]添加DNS记录”
  • “搭建DNS条目”
  • “让[service].temet.ai在本地解析”
隐含触发场景：
  • 向domains.toml添加新服务后
  • temet.ai域名在本地无法解析时
  • 全新安装Pi-hole后
  • 将服务迁移到新IP地址时
调试触发场景：
  • “DNS无法解析”
  • “无法在本地网络访问[service].temet.ai”
  • “dig返回错误IP”
  • “远程可访问但本地不行”

What This Skill Does

该技能的作用

  1. Detects Pi IP - Auto-discovers the Raspberry Pi's local IP address
  2. Reads Configuration - Gets domain list from domains.toml
  3. Updates DNS - Configures Pi-hole with local DNS entries via docker-compose.yml
  4. Verifies Resolution - Tests DNS resolution works correctly
  5. Provides Guidance - Reminds about router DNS configuration
  1. 检测树莓派IP - 自动发现树莓派的本地IP地址
  2. 读取配置 - 从domains.toml获取域名列表
  3. 更新DNS - 通过docker-compose.yml为Pi-hole配置本地DNS条目
  4. 验证解析 - 测试DNS解析是否正常工作
  5. 提供指导 - 提醒配置路由器DNS

Instructions

操作步骤

3.1 Detect Pi IP Address

3.1 检测树莓派IP地址

Get the Pi's local IP automatically:
bash
hostname -I | awk '{print $1}'
Expected output: 
192.168.68.135
(or similar)
Alternative methods if needed:
bash
undefined
自动获取树莓派本地IP：
bash
hostname -I | awk '{print $1}'
预期输出：
192.168.68.135
（或类似）
其他可选方法：
bash
undefined

From network interface

从网络接口获取

ip -4 addr show eth0 | grep -oP '(?<=inet\s)\d+(.\d+){3}'
ip -4 addr show eth0 | grep -oP '(?<=inet\s)\d+(.\d+){3}'

From Pi-hole container environment

从Pi-hole容器环境变量获取

docker exec pihole printenv | grep PIHOLE_INTERFACE
undefined
docker exec pihole printenv | grep PIHOLE_INTERFACE
undefined

3.2 Get Domains from Configuration

3.2 从配置文件获取域名

Read domains from 
domains.toml
:
bash
undefined
从
domains.toml
读取域名：
bash
undefined

List all configured services with DNS entries

列出所有配置了DNS条目的服务

./scripts/manage-domains.sh list

Or parse directly:

```bash
grep -E "^subdomain = |^dns_ip = " /home/dawiddutoit/projects/network/domains.toml
Current domains defined in domains.toml:
ServiceDomainDNS IP
Pi-holepihole.temet.ai192.168.68.135
Jaegerjaeger.temet.ai192.168.68.135
Langfuselangfuse.temet.ai192.168.68.135
Home Assistantha.temet.ai192.168.68.135
Code Servercode.temet.ai192.168.68.135
Sprinklersprinkler.temet.ai192.168.68.105
Webhookwebhook.temet.ai192.168.68.135
Roottemet.ai192.168.68.135
./scripts/manage-domains.sh list

或直接解析：

```bash
grep -E "^subdomain = |^dns_ip = " /home/dawiddutoit/projects/network/domains.toml
domains.toml中当前定义的域名：
服务域名DNS IP
Pi-holepihole.temet.ai192.168.68.135
Jaegerjaeger.temet.ai192.168.68.135
Langfuselangfuse.temet.ai192.168.68.135
Home Assistantha.temet.ai192.168.68.135
Code Servercode.temet.ai192.168.68.135
Sprinklersprinkler.temet.ai192.168.68.105
Webhookwebhook.temet.ai192.168.68.135
根域名temet.ai192.168.68.135

3.3 Apply DNS Changes

3.3 应用DNS变更

Automated Method (Recommended):
bash
cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply
This runs 
generate-pihole-dns.py
which:
  1. Reads domains.toml
  2. Updates 
    FTLCONF_dns_hosts
    in docker-compose.yml
  3. Restarts Pi-hole to apply changes
Manual DNS Entry (Single Domain):
If you need to add a single entry without full apply:
bash
undefined
自动化方法（推荐）：
bash
cd /home/dawiddutoit/projects/network && ./scripts/manage-domains.sh apply
该命令会运行
generate-pihole-dns.py
，执行以下操作：
  1. 读取domains.toml
  2. 更新docker-compose.yml中的
    FTLCONF_dns_hosts
  3. 重启Pi-hole以应用变更
手动添加DNS条目（单个域名）：
如果无需完整应用，仅需添加单个条目：
bash
undefined

Edit docker-compose.yml FTLCONF_dns_hosts section

编辑docker-compose.yml中的FTLCONF_dns_hosts部分

Then restart Pi-hole

然后重启Pi-hole

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

**How DNS Configuration Works:**

Pi-hole v6 uses `FTLCONF_dns_hosts` environment variable for custom DNS:

```yaml
environment:
  FTLCONF_dns_hosts: |
    192.168.68.135 pihole.temet.ai
    192.168.68.135 jaeger.temet.ai
    192.168.68.105 sprinkler.temet.ai
docker compose -f /home/dawiddutoit/projects/network/docker-compose.yml restart pihole

**DNS配置原理：**

Pi-hole v6使用`FTLCONF_dns_hosts`环境变量配置自定义DNS：

```yaml
environment:
  FTLCONF_dns_hosts: |
    192.168.68.135 pihole.temet.ai
    192.168.68.135 jaeger.temet.ai
    192.168.68.105 sprinkler.temet.ai

3.4 Verify DNS Resolution

3.4 验证DNS解析

After applying changes, verify DNS works:
Test individual domain:
bash
dig @localhost pihole.temet.ai +short
应用变更后，验证DNS是否正常工作：
测试单个域名：
bash
dig @localhost pihole.temet.ai +short

Expected: 192.168.68.135

预期输出：192.168.68.135


**Test all configured domains:**

```bash
for domain in pihole jaeger langfuse ha code webhook; do
  echo -n "$domain.temet.ai -> "
  dig @localhost $domain.temet.ai +short
done
Test from another device on the network:
bash
undefined

**测试所有配置的域名：**

```bash
for domain in pihole jaeger langfuse ha code webhook; do
  echo -n "$domain.temet.ai -> "
  dig @localhost $domain.temet.ai +short
done
从网络中的其他设备测试：
bash
undefined

Replace 192.168.68.135 with Pi's IP

将192.168.68.135替换为树莓派的IP

dig @192.168.68.135 pihole.temet.ai +short

**Check Pi-hole DNS logs:**

```bash
docker exec pihole pihole -t
dig @192.168.68.135 pihole.temet.ai +short

**查看Pi-hole DNS日志：**

```bash
docker exec pihole pihole -t

Watch live DNS queries

实时查看DNS查询日志

undefined
undefined

3.5 Router DNS Reminder

3.5 路由器DNS配置提醒

Important: For DNS to work network-wide, configure your router:
  1. Set router's DHCP to use Pi-hole as primary DNS:
    • Primary DNS: 
      192.168.68.135
      (Pi's IP)
    • Secondary DNS: 
      1.1.1.1
      (fallback)
  2. Or configure each device individually to use Pi-hole DNS
Verify device is using Pi-hole:
bash
undefined
重要提示： 要让DNS在整个网络生效，需配置路由器：
  1. 将路由器的DHCP设置为使用Pi-hole作为主DNS：
    • 主DNS：
      192.168.68.135
      （树莓派的IP）
    • 备用DNS：
      1.1.1.1
      （备用选项）
  2. 或者为每个设备单独配置使用Pi-hole DNS
验证设备是否使用Pi-hole：
bash
undefined

On the device, check what DNS server it's using

在设备上查看正在使用的DNS服务器

cat /etc/resolv.conf
cat /etc/resolv.conf

Should show: nameserver 192.168.68.135

应显示：nameserver 192.168.68.135

undefined
undefined

Supporting Files

支持文件

FilePurpose
references/reference.md
DNS configuration deep-dive, Pi-hole internals, troubleshooting
examples/examples.md
Common scenarios and configurations
scripts/verify-dns.sh
DNS verification script
文件用途
references/reference.md
DNS配置深入解析、Pi-hole内部原理、故障排查
examples/examples.md
常见场景与配置示例
scripts/verify-dns.sh
DNS验证脚本

Expected Outcomes

预期结果

Success:
  • All domains resolve to correct IPs locally
  • dig @localhost domain.temet.ai
    returns expected IP
  • Services accessible at 
    https://domain.temet.ai
    on local network
Partial Success:
  • DNS works from Pi but not from other devices
  • Cause: Router not configured to use Pi-hole as DNS
Failure Indicators:
  • dig
    returns NXDOMAIN -> DNS entry not configured
  • dig
    returns wrong IP -> Stale configuration
  • Pi-hole not responding -> Container not running
成功：
  • 所有域名在本地解析到正确IP
  • dig @localhost domain.temet.ai
    返回预期IP
  • 可在本地网络通过
    https://domain.temet.ai
    访问服务
部分成功：
  • DNS在树莓派上正常工作，但在其他设备上不行
  • 原因：路由器未配置为使用Pi-hole作为DNS
失败迹象：
  • dig
    返回NXDOMAIN -> DNS条目未配置
  • dig
    返回错误IP -> 配置过期
  • Pi-hole无响应 -> 容器未运行

Requirements

环境要求

Environment:
  • Pi-hole container running: 
    docker ps | grep pihole
  • Docker Compose available
  • domains.toml configured
Tools needed:
  • Read (configuration files)
  • Bash (dig, docker commands)
  • Grep (parsing domains)
环境：
  • Pi-hole容器正在运行：
    docker ps | grep pihole
  • 已安装Docker Compose
  • domains.toml已配置
所需工具：
  • 读取权限（配置文件）
  • Bash（dig、docker命令）
  • Grep（解析域名）

Red Flags to Avoid

注意事项

  • Do not add DNS entries directly to Pi-hole web UI (use domains.toml)
  • Do not forget to restart Pi-hole after config changes
  • Do not skip the router DNS configuration reminder
  • Do not use 
    127.0.0.1
    as DNS IP (use actual Pi IP)
  • Do not assume DNS propagates instantly (may take 1-2 minutes)
  • Do not forget IoT devices may need different IPs (sprinkler -> 192.168.68.105)
  • 不要直接在Pi-hole网页UI中添加DNS条目（请使用domains.toml）
  • 配置变更后不要忘记重启Pi-hole
  • 不要忽略路由器DNS配置提醒
  • 不要使用
    127.0.0.1
    作为DNS IP（请使用树莓派实际IP）
  • 不要假设DNS会立即生效（可能需要1-2分钟）
  • 不要忘记IoT设备可能需要不同的IP（如sprinkler -> 192.168.68.105）

Notes

备注

  • DNS entries are stored in docker-compose.yml 
    FTLCONF_dns_hosts
  • The 
    generate-pihole-dns.py
    script reads domains.toml and updates docker-compose.yml
  • Local DNS resolution allows fast LAN access without internet roundtrip
  • Remote access uses Cloudflare DNS (separate from Pi-hole)
  • Always verify DNS after changes with 
    dig @localhost domain +short
  • DNS条目存储在docker-compose.yml的
    FTLCONF_dns_hosts
    中
  • generate-pihole-dns.py
    脚本读取domains.toml并更新docker-compose.yml
  • 本地DNS解析可实现快速局域网访问，无需绕路互联网
  • 远程访问使用Cloudflare DNS（与Pi-hole分离）
  • 变更后请始终使用
    dig @localhost domain +short
    验证DNS