|
1 | | -# 🛠️ Pi-hole v6 - Troubleshooting Guide |
| 1 | +# 🛠️ Pi-hole v6 Troubleshooting Guide (2025) |
2 | 2 |
|
3 | | -This guide provides solutions to common issues encountered when using Pi-hole v6, including DNS resolution problems, blocking issues, network conflicts, and performance optimizations. |
| 3 | +Stack: Pi-hole Core 6.1.4 / FTL 6.1 / Web 6.2 on Raspberry Pi 3/4 (Debian Bookworm/Trixie). Built-in web server only—no lighttpd. |
4 | 4 |
|
5 | 5 | --- |
6 | 6 |
|
7 | | -## 📌 1. DNS Resolution Issues |
| 7 | +## 1) Port 53 Conflicts (systemd-resolved/dnsmasq) |
8 | 8 |
|
9 | | -### 🔹 Pi-hole is not blocking ads |
| 9 | +- Check listeners: `ss -tulpn | grep ':53' || netstat -tulpn | grep ':53'`. |
| 10 | +- Disable conflicting resolvers: `sudo systemctl disable --now systemd-resolved`; stop other DNS daemons or Docker containers binding 53. |
| 11 | +- Reapply Pi-hole DNS bindings: `sudo pihole restartdns`. |
| 12 | +- Validate with `scripts/v6-upgrade-check.sh` (includes port 53 checks) and ensure clients use only the Pi-hole IP. |
10 | 13 |
|
11 | | -✅ **Solution:** |
| 14 | +## 2) FTL DB Corruption / Web UI 403 (built-in server) |
12 | 15 |
|
13 | | -1. Ensure that your device is using Pi-hole as the primary DNS: |
| 16 | +- Repair DB safely: `sudo bash scripts/fix-ftl-db.sh` (backs up `pihole-FTL.db`, recreates indexes). |
| 17 | +- Fix 403 or missing `pihole.toml`: `sudo bash scripts/fix-ui-403.sh` to refresh built-in web server permissions. |
| 18 | +- Restart services: `sudo pihole restartdns` and `sudo systemctl status pihole-FTL`. |
| 19 | +- Still broken? Run `sudo pihole -r --reconfigure` to rebuild the v6 config, then rerun the fix scripts if needed. |
14 | 20 |
|
15 | | - ```bash |
16 | | - nslookup pi.hole |
17 | | - ``` |
| 21 | +## 3) DNS Outages / Upstream Failures |
18 | 22 |
|
19 | | - If it fails, your router may be overriding DNS settings. Manually configure your device’s DNS. |
| 23 | +- Unbound path: `dig @127.0.0.1 -p 5335 example.com`; if it fails, restart Unbound or update root hints. |
| 24 | +- Pi-hole path: `sudo pihole -g && sudo pihole restartdns`; confirm `pihole-FTL` is `active (running)`. |
| 25 | +- Run `sudo bash scripts/v6-upgrade-check.sh` to catch known v6.1 upgrade issues (pihole.toml missing, bad upstreams). |
| 26 | +- Docker users: verify host networking with `scripts/docker-verify.sh` if running Pi-hole in a container. |
20 | 27 |
|
21 | | -2. Restart Pi-hole: |
| 28 | +## 4) DHCP & Client Visibility |
22 | 29 |
|
23 | | - ```bash |
24 | | - pihole restartdns |
25 | | - ``` |
| 30 | +- Enable Pi-hole DHCP for per-client logs: `sudo bash scripts/enable-dhcp.sh`. |
| 31 | +- Disable router DNS helpers/rebind protection that overwrite client DNS. |
| 32 | +- Block DNS bypass: firewall outbound port 53/853 to anything except Pi-hole and your upstream/Unbound box. |
| 33 | +- After enabling DHCP, renew leases on clients or reboot access points. |
26 | 34 |
|
27 | | -3. Check if the blocklists are up-to-date: |
| 35 | +## Quick References |
28 | 36 |
|
29 | | - ```bash |
30 | | - pihole -g |
31 | | - ``` |
32 | | - |
33 | | -### 🔹 Sites are slow to load / DNS queries take too long |
34 | | - |
35 | | -✅ **Solution:** |
36 | | - |
37 | | -1. Check query time: |
38 | | - |
39 | | - ```bash |
40 | | - dig google.com @127.0.0.1 -p 5335 |
41 | | - ``` |
42 | | - |
43 | | -2. Ensure that Unbound or the upstream DNS is responsive. |
44 | | - |
45 | | -3. Optimize the cache size in unbound.conf: |
46 | | - |
47 | | - ``` |
48 | | - cache-max-ttl: 86400 |
49 | | - cache-min-ttl: 3600 |
50 | | - ``` |
51 | | - |
52 | | -### 🔹 Pi-hole is not resolving local domains |
53 | | - |
54 | | -✅ **Solution:** |
55 | | - |
56 | | -1. Add local DNS records: |
57 | | - |
58 | | - ```bash |
59 | | - sudo nano /etc/pihole/custom.list |
60 | | - ``` |
61 | | - |
62 | | - Example entry: |
63 | | - |
64 | | - ``` |
65 | | - 192.168.1.100 myserver.local |
66 | | - ``` |
67 | | - |
68 | | -2. Restart DNS: |
69 | | - |
70 | | - ```bash |
71 | | - pihole restartdns |
72 | | - ``` |
73 | | - |
74 | | ---- |
75 | | - |
76 | | -## 🔧 2. Whitelisting & Blocklist Issues |
77 | | - |
78 | | -### 🔹 A website is blocked even after whitelisting |
79 | | - |
80 | | -✅ **Solution:** |
81 | | - |
82 | | -1. Check if the domain is still blocked: |
83 | | - |
84 | | - ```bash |
85 | | - pihole -q example.com |
86 | | - ``` |
87 | | - |
88 | | -2. Force Pi-hole to update lists: |
89 | | - |
90 | | - ```bash |
91 | | - pihole restartdns |
92 | | - ``` |
93 | | - |
94 | | -3. Manually whitelist: |
95 | | - |
96 | | - ```bash |
97 | | - pihole -w example.com |
98 | | - ``` |
99 | | - |
100 | | -### 🔹 Blocklists are not updating |
101 | | - |
102 | | -✅ **Solution:** |
103 | | - |
104 | | -1. Manually update: |
105 | | - |
106 | | - ```bash |
107 | | - pihole -g |
108 | | - ``` |
109 | | - |
110 | | -2. Check for errors: |
111 | | - |
112 | | - ```bash |
113 | | - cat /var/log/pihole_updateGravity.log |
114 | | - ``` |
115 | | - |
116 | | ---- |
117 | | - |
118 | | -## 🌍 3. IPv6 & Network Issues |
119 | | - |
120 | | -### 🔹 IPv6 Queries are not being blocked |
121 | | - |
122 | | -✅ **Solution:** |
123 | | - |
124 | | -1. Ensure Pi-hole is handling IPv6: |
125 | | - |
126 | | - ```bash |
127 | | - dig AAAA example.com @127.0.0.1 -p 5335 |
128 | | - ``` |
129 | | - |
130 | | -2. If required, force all clients to use IPv4: |
131 | | - |
132 | | - ```bash |
133 | | - pihole -a setdns 192.168.1.2 |
134 | | - ``` |
135 | | - |
136 | | -### 🔹 Some devices bypass Pi-hole |
137 | | - |
138 | | -✅ **Solution:** |
139 | | - |
140 | | -1. Ensure that your router only assigns Pi-hole’s IP as DNS. |
141 | | - |
142 | | -2. Block external DNS on the router firewall: |
143 | | - |
144 | | - ```bash |
145 | | - sudo iptables -A OUTPUT -p udp --dport 53 -j REJECT |
146 | | - ``` |
147 | | - |
148 | | -3. If the device uses DoH/DoT (DNS over HTTPS/TLS), block common DoH servers. |
149 | | - |
150 | | ---- |
151 | | - |
152 | | -## 4. Performance & Optimization |
153 | | - |
154 | | -### 🔹 Pi-hole uses too much memory |
155 | | - |
156 | | -✅ **Solution:** |
157 | | - |
158 | | -1. Reduce the number of blocklists: |
159 | | - |
160 | | - ```bash |
161 | | - pihole -a -b remove_list_url |
162 | | - ``` |
163 | | - |
164 | | -2. Reduce FTL cache size in /etc/pihole/pihole-FTL.conf: |
165 | | - |
166 | | - ``` |
167 | | - MAXDBDAYS=7 |
168 | | - DBINTERVAL=60.0 |
169 | | - ``` |
170 | | - |
171 | | -### 🔹 Reduce Unbound CPU usage |
172 | | - |
173 | | -✅ **Solution:** |
174 | | - |
175 | | -1. Optimize the Unbound configuration: |
176 | | - |
177 | | - ``` |
178 | | - num-threads: 1 |
179 | | - msg-cache-size: 4m |
180 | | - rrset-cache-size: 8m |
181 | | - ``` |
182 | | - |
183 | | ---- |
184 | | - |
185 | | -## 🛑 5. Debugging & Logs |
186 | | - |
187 | | -### 🔹 How to check live logs |
188 | | - |
189 | | -```bash |
190 | | -pihole -t |
191 | | -``` |
192 | | - |
193 | | -### 🔹 Check DNS query logs |
194 | | - |
195 | | -```bash |
196 | | -cat /var/log/pihole.log | grep example.com |
197 | | -``` |
198 | | - |
199 | | -### 🔹 Enable FTL debugging for deeper analysis |
200 | | - |
201 | | -```bash |
202 | | -pihole checkout ftl debug |
203 | | -``` |
204 | | - |
205 | | ---- |
206 | | - |
207 | | -## 📝 6. Reporting Issues |
208 | | - |
209 | | -If the issue persists, generate a debug log and submit it: |
210 | | - |
211 | | -```bash |
212 | | -pihole -d |
| 37 | +- Logs: `sudo journalctl -u pihole-FTL -f` |
| 38 | +- Health: `sudo pihole status` and `dig pi.hole @<PIHOLE-IP>` |
| 39 | +- Backups: use `scripts/backup-restore.sh` before major upgrades. |
0 commit comments