Skip to content

Commit 85e8804

Browse files
authored
colon consistency (#24)
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
1 parent 496c3a7 commit 85e8804

4 files changed

Lines changed: 43 additions & 43 deletions

File tree

src/content/docs/pi-hole/block-allow-lists.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -184,9 +184,9 @@ To add a list:
184184

185185
There are two ways to allowlist in Pi-hole v6:
186186

187-
- **List subscriptions:** Subscribe to a URL and Pi-hole manages it automatically, like a blocklist.
187+
- **List subscriptions**: Subscribe to a URL and Pi-hole manages it automatically, like a blocklist.
188188
Best for maintained collections of domains.
189-
- **Individual domain entries:** Add a single domain directly in **Domains** > **Allowlist** in the web interface.
189+
- **Individual domain entries**: Add a single domain directly in **Domains** > **Allowlist** in the web interface.
190190
Best for one-off fixes when a specific service breaks.
191191

192192
### Subscribe to a referral allowlist

src/content/docs/pi-hole/network-level-blocking.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ This happens automatically when the lease expires (typically within 24 hours, de
5858

5959
For a smart TV, that means a full power cycle from the menu or the old favorite: unplug it, then plug it back in.
6060

61-
**Verify it's working:** On a device that has renewed its lease, open the Pi-hole query log and browse to a few sites - you should see the device's IP appear as a client.
61+
**Verify it's working**: On a device that has renewed its lease, open the Pi-hole query log and browse to a few sites - you should see the device's IP appear as a client.
6262

6363
## Optional: Force Devices That Ignore Router DNS to Use the Pi-hole
6464

src/content/docs/pi-hole/tailscale.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -150,13 +150,13 @@ Advertising an exit node doesn't automatically route traffic through it.
150150

151151
Each client enables its own exit node options.
152152

153-
- **macOS / Windows:**
153+
- **macOS / Windows**:
154154
- Open the Tailscale menu bar app > **Exit Node** > select your Pi by name.
155155

156-
- **iOS / Android:**
156+
- **iOS / Android**:
157157
- Open the Tailscale app > select your tailnet name > **Use exit node** > select the Pi.
158158

159-
- **Linux:**
159+
- **Linux**:
160160
- Run on the client device (not the Pi), using the `100.x.x.x` Tailscale IP from above:
161161

162162
```shell title="From the client device"

src/content/docs/pi-hole/troubleshooting.mdx

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,11 @@ Change `true` to `false` when you're done troubleshooting.
2727

2828
### SSH host key mismatch after rebuild
2929

30-
**Symptom:** `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED` when SSHing to the Pi.
30+
**Symptom**: `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED` when SSHing to the Pi.
3131

32-
**Cause:** You reformatted the SD card and reinstalled, or changed the IP address, but your computer still has the old SSH host key cached.
32+
**Cause**: You reformatted the SD card and reinstalled, or changed the IP address, but your computer still has the old SSH host key cached.
3333

34-
**Fix:**
34+
**Fix**:
3535

3636
```shell title="From your device"
3737
ssh-keygen -R pi-hole.local
@@ -40,20 +40,20 @@ ssh pi-admin@pi-hole.local
4040

4141
### Port 53 conflict between Pi-hole and unbound
4242

43-
**Symptom:** Pi-hole installs successfully, the web interface works, but DNS resolution fails on your network. The dashboard may show "DNS server failure."
43+
**Symptom**: Pi-hole installs successfully, the web interface works, but DNS resolution fails on your network. The dashboard may show "DNS server failure."
4444

45-
**Cause:** Both Pi-hole (via dnsmasq) and unbound are trying to listen on port 53.
45+
**Cause**: Both Pi-hole (via dnsmasq) and unbound are trying to listen on port 53.
4646
This happens if unbound was installed with its default configuration before Pi-hole.
4747

48-
**Check:**
48+
**Check**:
4949

5050
```shell title="From the Pi"
5151
sudo journalctl -u pihole-FTL | grep "port 53"
5252
```
5353

5454
Look for: `dnsmasq: failed to create listening socket for port 53: Address in use`
5555

56-
**Fix:** Configure unbound to use port 5335 (see [Optional: Configure Unbound as Recursive DNS](./pihole-install/#optional-configure-unbound-as-recursive-dns)), then restart both services:
56+
**Fix**: Configure unbound to use port 5335 (see [Optional: Configure Unbound as Recursive DNS](./pihole-install/#optional-configure-unbound-as-recursive-dns)), then restart both services:
5757

5858
```shell title="From the Pi"
5959
sudo systemctl restart unbound
@@ -62,34 +62,34 @@ sudo systemctl restart pihole-FTL
6262

6363
### Pi-hole web interface shows 403 Forbidden or won't load
6464

65-
**Symptom:** `https://pi-hole.local/admin` returns 403 Forbidden or the page won't connect.
65+
**Symptom**: `https://pi-hole.local/admin` returns 403 Forbidden or the page won't connect.
6666

67-
**Most common cause:** lighttpd (the v5-era web server) is installed and running, occupying port 80.
67+
**Most common cause**: lighttpd (the v5-era web server) is installed and running, occupying port 80.
6868
Pi-hole v6 has its own embedded web server - if lighttpd grabs port 80 first, FTL falls back to port 8080 silently.
6969

70-
**Check:**
70+
**Check**:
7171

7272
```shell title="From the Pi"
7373
sudo systemctl status lighttpd
7474
```
7575

76-
**Fix:**
76+
**Fix**:
7777

7878
```shell title="From the Pi"
7979
sudo systemctl stop lighttpd
8080
sudo systemctl disable lighttpd
8181
sudo systemctl restart pihole-FTL
8282
```
8383

84-
**Check what port FTL is actually using:**
84+
**Check what port FTL is actually using**:
8585

8686
```shell title="From the Pi"
8787
pihole-FTL --config webserver.port
8888
```
8989

9090
If it shows `8080`, try `http://pi-hole.local:8080/admin` as a temporary workaround.
9191

92-
**Secondary cause:** FTL is not running at all.
92+
**Secondary cause**: FTL is not running at all.
9393

9494
```shell title="From the Pi"
9595
sudo systemctl status pihole-FTL
@@ -100,14 +100,14 @@ The most common reason on a fresh install is a port 53 conflict - see above.
100100

101101
### Gravity fails to update
102102

103-
**Symptom:** Running `sudo pihole -g` exits with "DNS resolution is currently unavailable"
103+
**Symptom**: Running `sudo pihole -g` exits with "DNS resolution is currently unavailable"
104104
or "list download failed: no cached list available."
105105

106-
**Cause:** `/etc/resolv.conf` points to `127.0.0.1` (Pi-hole itself).
106+
**Cause**: `/etc/resolv.conf` points to `127.0.0.1` (Pi-hole itself).
107107
If FTL isn't fully ready when Gravity runs - for example, immediately after install
108108
before the first restart - the DNS lookup for list URLs fails.
109109

110-
**Fix:** Wait 30 seconds after install completes, confirm FTL is running, then re-run:
110+
**Fix**: Wait 30 seconds after install completes, confirm FTL is running, then re-run:
111111

112112
```shell title="From the Pi"
113113
sudo systemctl status pihole-FTL
@@ -121,19 +121,19 @@ dig raw.githubusercontent.com @1.1.1.1
121121
curl -v https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/adblock/multi.txt
122122
```
123123

124-
**Note:** The web interface Gravity button can silently fail in some FTL versions.
124+
**Note**: The web interface Gravity button can silently fail in some FTL versions.
125125
If the dashboard shows an error but `sudo pihole -g` from the terminal succeeds, use the CLI.
126126

127127
### Maximum number of concurrent DNS queries reached
128128

129-
**Symptom:** DNS becomes unresponsive. The FTL log shows:
129+
**Symptom**: DNS becomes unresponsive. The FTL log shows:
130130
`Maximum number of concurrent DNS queries reached (max: 150)`
131131

132-
**Most common cause:** A DNS loop - Pi-hole is forwarding queries to itself.
132+
**Most common cause**: A DNS loop - Pi-hole is forwarding queries to itself.
133133
Check **Settings** > **DNS** and confirm the upstream servers are not `127.0.0.1`
134134
or the Pi's own LAN IP.
135135

136-
**Check:**
136+
**Check**:
137137

138138
<Steps>
139139

@@ -154,35 +154,35 @@ or the Pi's own LAN IP.
154154

155155
</Steps>
156156

157-
**Fix:** In **Settings** > **All Settings** > **DNS**, raise `dns.maxConcurrent` to `300` or `500`.
157+
**Fix**: In **Settings** > **All Settings** > **DNS**, raise `dns.maxConcurrent` to `300` or `500`.
158158
Treat this as a symptom fix.
159159
Find the root cause (DNS loop or misbehaving client) separately.
160160

161161
### Intermittent DNS failures with unbound
162162

163-
**Symptom:** DNS works, then randomly stops for minutes several times a day.
163+
**Symptom**: DNS works, then randomly stops for minutes several times a day.
164164
Restarting FTL or unbound temporarily fixes it.
165165
Switching to Cloudflare upstream eliminates the problem.
166166

167-
**Cause:** Unbound periodically fails to respond within FTL's timeout.
167+
**Cause**: Unbound periodically fails to respond within FTL's timeout.
168168
This can happen when unbound needs to re-validate DNSSEC chains or when its root hint cache is stale.
169169

170-
**Check:** Test unbound independently while Pi-hole is failing:
170+
**Check**: Test unbound independently while Pi-hole is failing:
171171

172172
```shell title="From the Pi"
173173
dig google.com @127.0.0.1 -p 5335
174174
```
175175

176176
If this returns `SERVFAIL` or times out, the problem is in unbound, not FTL.
177177

178-
**Fix - refresh root hints:**
178+
**Fix - refresh root hints**:
179179

180180
```shell title="From the Pi"
181181
sudo unbound-anchor -a /var/lib/unbound/root.key
182182
sudo systemctl restart unbound
183183
```
184184

185-
**Fix - check unbound logs:**
185+
**Fix - check unbound logs**:
186186

187187
```shell title="From the Pi"
188188
sudo journalctl -u unbound -n 100
@@ -192,25 +192,25 @@ Look for `SERVFAIL`, timeout, or `DNSSEC` validation failure messages.
192192

193193
### FTL database grows too large and FTL fails to start
194194

195-
**Symptom (weeks or months after setup):** After a reboot, Pi-hole never comes back online.
195+
**Symptom (weeks or months after setup)**: After a reboot, Pi-hole never comes back online.
196196
`systemctl status pihole-FTL` shows failed.
197197

198198
The journal shows:
199199
`CRIT: realloc_shm(): Failed to resize "FTL-queries": No space left on device`
200200

201-
**Cause:** Pi-hole v6 stores every DNS query for 91 days by default.
201+
**Cause**: Pi-hole v6 stores every DNS query for 91 days by default.
202202
Pi-hole v5 has a default of 365 days.
203203
If you have Pi-hole v5 or upgraded from it, check your `maxDBdays` setting.
204204

205-
**Quick fix (loses query history):**
205+
**Quick fix (loses query history)**:
206206

207207
```shell title="From the Pi"
208208
sudo systemctl stop pihole-FTL
209209
sudo rm /etc/pihole/pihole-FTL.db
210210
sudo systemctl start pihole-FTL
211211
```
212212

213-
**Prevention:** Verify your retention setting in `/etc/pihole/pihole.toml`:
213+
**Prevention**: Verify your retention setting in `/etc/pihole/pihole.toml`:
214214

215215
```toml title="/etc/pihole/pihole.toml"
216216
[database]
@@ -223,20 +223,20 @@ Refer to the [example pihole.toml](./maintenance/#reference-full-piholetoml) in
223223

224224
### NTP warnings in the Pi-hole dashboard
225225

226-
**Symptom:** Dashboard shows "No valid NTP replies received" or "Standard deviation of time offset is too large, rejecting synchronization."
226+
**Symptom**: Dashboard shows "No valid NTP replies received" or "Standard deviation of time offset is too large, rejecting synchronization."
227227

228-
**Cause:** Pi-hole v6 has its own NTP client that runs alongside the OS time sync (`systemd-timesyncd`).
228+
**Cause**: Pi-hole v6 has its own NTP client that runs alongside the OS time sync (`systemd-timesyncd`).
229229
Occasionally an NTP pool server times out.
230230

231-
**Check:** Verify the system clock is correct:
231+
**Check**: Verify the system clock is correct:
232232

233233
```shell title="From the Pi"
234234
timedatectl status
235235
```
236236

237237
If `System clock synchronized: yes` and the time is correct, the warning is cosmetic.
238238

239-
**Optional fix:** Disable Pi-hole's NTP client since the OS handles time sync:
239+
**Optional fix**: Disable Pi-hole's NTP client since the OS handles time sync:
240240

241241
```shell title="From the Pi"
242242
sudo pihole-FTL --config ntp.sync.active false
@@ -318,19 +318,19 @@ Regex rules can cause false positives that don't show up until something breaks.
318318

319319
#### Gravity shows "Invalid protocol" errors for domain names
320320

321-
**Symptom:**: `sudo pihole -g` shows errors like:
321+
**Symptom**: `sudo pihole -g` shows errors like:
322322

323323
```shellsession title="From the Pi"
324324
[✗] Status: Invalid protocol specified. Ignoring list.
325325
Ensure your URL starts with a valid protocol like http:// , https:// or file:// .
326326
[✗] Status: geolocation.onetrust.com ()
327327
```
328328

329-
**Cause:** Individual domain names were added to **Lists** instead of **Domains** > **Allowlist**.
329+
**Cause**: Individual domain names were added to **Lists** instead of **Domains** > **Allowlist**.
330330
Pi-hole's Gravity system downloads list files (usually `.txt`) from URLs.
331331
It can't process bare domain names as list entries.
332332

333-
**Fix:** In the web interface, go to **Lists** and delete any entries that are bare domain names (not URLs starting with `https://`).
333+
**Fix**: In the web interface, go to **Lists** and delete any entries that are bare domain names (not URLs starting with `https://`).
334334
Then re-add those domains via CLI or under **Domains** > **Allowlist**:
335335

336336
```shell title="From the Pi"

0 commit comments

Comments
 (0)