# Pi-hole

## Purpose

Pi-hole provides DNS services for the Bytek home network.

Pi-hole is responsible for:

<div id="bkmrk-resolving-public-int" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Resolving public internet hostnames.
- Blocking selected advertising and tracking domains.
- Providing split-DNS records for Bytek applications.
- Providing DHCP reservations for infrastructure guests.
- Directing internal application traffic to Traefik.
- Resolving the private Proxmox hostname.
- Providing DNS to selected Docker containers.

</div>Pi-hole is foundational infrastructure. Pi-hole must remain accessible independently of Traefik and Authentik so DNS can be repaired during an application or identity outage.

<div id="bkmrk-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Service Information

<div id="bkmrk-setting-value-servic" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Setting</th><th>Value</th></tr><tr><td>Service name</td><td>Pi-hole</td></tr><tr><td>Private IP address</td><td>`192.168.2.65`</td></tr><tr><td>LAN subnet</td><td>`192.168.2.0/24`</td></tr><tr><td>DNS ports</td><td>TCP and UDP 53</td></tr><tr><td>Primary role</td><td>LAN DNS and split DNS</td></tr><tr><td>Secondary role</td><td>DHCP reservations</td></tr><tr><td>Management scope</td><td>Home LAN or trusted VPN</td></tr><tr><td>Authentication</td><td>Local Pi-hole credentials</td></tr><tr><td>Proxmox guest type</td><td>LXC</td></tr><tr><td>Proxmox guest ID</td><td>Confirm current CT ID</td></tr><tr><td>Backup coverage</td><td>Proxmox scheduled backup</td></tr></tbody></table>

</div></div>---

</div>## Architecture Role

Pi-hole provides DNS to home-LAN clients and selected infrastructure containers.

When a LAN device opens a Bytek application:

<div id="bkmrk-the-device-asks-pi-h" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. The device asks Pi-hole to resolve the application hostname.
2. Pi-hole returns Traefik’s private address, `192.168.2.182`.
3. The client connects directly to Traefik.
4. Traefik routes the request to the correct private application backend.

</div>This allows the same hostname and HTTPS certificate to be used internally and externally.

Pi-hole is not part of the public application path for external users.

External users resolve Bytek applications through WHC public DNS instead.

<div id="bkmrk--1" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## DNS Responsibilities

Pi-hole provides two types of DNS resolution.

### Public Internet Resolution

Pi-hole forwards normal public DNS queries to its configured upstream resolvers.

Examples include:

<div id="bkmrk-software-repositorie" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Software repositories.
- Linux package mirrors.
- Let’s Encrypt.
- Docker registries.
- Public websites.
- Public APIs.

</div>### Local Bytek Resolution

Pi-hole answers selected Bytek application hostnames using private addresses.

These local records create the split-DNS design.

<div id="bkmrk--2" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Split-DNS Records

<div id="bkmrk-hostname-internal-de" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Hostname</th><th>Internal Destination</th><th>Purpose</th></tr><tr><td>`cloud.bytek.ca`</td><td>`192.168.2.182`</td><td>Nextcloud through Traefik</td></tr><tr><td>`docs.bytek.ca`</td><td>`192.168.2.182`</td><td>BookStack through Traefik</td></tr><tr><td>`portal.bytek.ca`</td><td>`192.168.2.182`</td><td>Authentik through Traefik</td></tr><tr><td>`projects.bytek.ca`</td><td>`192.168.2.182`</td><td>Vikunja through Traefik</td></tr><tr><td>`proxy.bytek.ca`</td><td>`192.168.2.182`</td><td>Traefik dashboard</td></tr><tr><td>`status.bytek.ca`</td><td>`192.168.2.182`</td><td>Uptime Kuma through Traefik</td></tr><tr><td>`pve.bytek.ca`</td><td>`192.168.2.254`</td><td>Direct Proxmox management</td></tr></tbody></table>

</div></div></div>Application hostnames point internally to Traefik.

Proxmox is the exception because Proxmox does not sit behind Traefik.

<div id="bkmrk--3" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Public and Private DNS Comparison

<div id="bkmrk-hostname-public-whc-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Hostname</th><th>Public WHC Result</th><th>Internal Pi-hole Result</th></tr><tr><td>`cloud.bytek.ca`</td><td>`38.29.213.101`</td><td>`192.168.2.182`</td></tr><tr><td>`docs.bytek.ca`</td><td>`38.29.213.101`</td><td>`192.168.2.182`</td></tr><tr><td>`portal.bytek.ca`</td><td>`38.29.213.101`</td><td>`192.168.2.182`</td></tr><tr><td>`projects.bytek.ca`</td><td>`38.29.213.101`</td><td>`192.168.2.182`</td></tr><tr><td>`proxy.bytek.ca`</td><td>`38.29.213.101`</td><td>`192.168.2.182`</td></tr><tr><td>`status.bytek.ca`</td><td>`38.29.213.101`</td><td>`192.168.2.182`</td></tr><tr><td>`pve.bytek.ca`</td><td>No public record</td><td>`192.168.2.254`</td></tr></tbody></table>

</div></div></div>The split-DNS model provides:

<div id="bkmrk-lower-latency-for-la" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Lower latency for LAN clients.
- No unnecessary traffic through the VPS.
- No dependency on router hairpin NAT.
- Consistent application URLs.
- Consistent OIDC callback addresses.
- Valid HTTPS certificates on internal connections.

---

</div>## Proxmox DNS Exception

The Proxmox host intentionally does not use Pi-hole as its general DNS resolver.

Proxmox uses:

<div id="bkmrk-dns-resolver%3A-9.9.9." style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **DNS resolver:** `9.9.9.9`

</div>This prevents the hypervisor from depending on a guest LXC for DNS.

As a result:

<div id="bkmrk-lan-clients-resolve-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- LAN clients resolve `portal.bytek.ca` to `192.168.2.182`.
- Proxmox normally resolves `portal.bytek.ca` to the VPS at `38.29.213.101`.

</div>Do not change the Proxmox resolver to Pi-hole without reviewing the dependency impact.

If Proxmox eventually needs a direct local route to Authentik, use a specific `/etc/hosts` entry for `portal.bytek.ca` instead of replacing the general resolver.

<div id="bkmrk--4" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## DHCP Reservations

Infrastructure guests should receive stable addresses through DHCP reservations.

Reservations are based on the virtual NIC MAC address assigned by Proxmox.

### Known Reservations

<div id="bkmrk-service-reserved-add" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Service</th><th>Reserved Address</th></tr><tr><td>Nextcloud AIO</td><td>`192.168.2.100`</td></tr><tr><td>Uptime Kuma</td><td>`192.168.2.115`</td></tr><tr><td>Vikunja</td><td>`192.168.2.121`</td></tr><tr><td>Authentik</td><td>`192.168.2.162`</td></tr><tr><td>Traefik</td><td>`192.168.2.182`</td></tr><tr><td>BookStack</td><td>Confirm current address</td></tr><tr><td>Plex</td><td>Confirm after deployment</td></tr><tr><td>Future game server</td><td>Confirm after deployment</td></tr></tbody></table>

</div></div></div>The WireGuard gateway uses `192.168.2.64`.

Confirm whether the WireGuard address is configured through a reservation or static guest networking before editing it.

<div id="bkmrk--5" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Why Stable Addresses Matter

Infrastructure addresses are referenced by:

<div id="bkmrk-traefik-backend-defi" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Traefik backend definitions.
- Proxmox firewall rules.
- Uptime Kuma monitors.
- Authentik Proxy Providers.
- Docker DNS settings.
- BookStack documentation.
- Administrative bookmarks.
- WireGuard forwarding rules.
- Application trusted-proxy settings.

</div>An unexpected address change can break several services simultaneously.

Always reserve a service address before treating the address as permanent.

<div id="bkmrk--6" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Finding a Guest MAC Address

For a Proxmox VM, inspect the `net0` entry using:

`qm config <VMID>`

For an LXC, inspect the network entry using:

`pct config <CTID>`

Record the MAC address in Pi-hole when creating the reservation.

Do not manually duplicate a MAC address between guests.

<div id="bkmrk--7" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## DNS Clients

Pi-hole may provide DNS to:

<div id="bkmrk-windows-workstations" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Windows workstations.
- Linux workstations.
- Mobile devices on the LAN.
- Service VMs.
- Service LXCs.
- Selected Docker containers.
- Future remote VPN clients.
- Uptime Kuma.
- Traefik.
- Nextcloud application containers.
- BookStack.
- Vikunja.

</div>Not every infrastructure host must use Pi-hole.

Proxmox intentionally uses Quad9.

Other critical systems may also use an independent resolver if avoiding a dependency on Pi-hole is more important than split-DNS access.

<div id="bkmrk--8" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Docker DNS

Some application containers require explicit Pi-hole DNS.

This is particularly important for containers that must resolve private Bytek hostnames.

### Traefik

The Traefik container explicitly uses:

<div id="bkmrk-192.168.2.65" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `192.168.2.65`

</div>This was added after Docker’s embedded resolver failed to resolve the Let’s Encrypt ACME endpoint following a power interruption.

### Uptime Kuma

The Uptime Kuma container explicitly uses:

<div id="bkmrk-192.168.2.65-1" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `192.168.2.65`

</div>This allows Kuma to monitor private Bytek application hostnames.

### BookStack

BookStack may use Pi-hole explicitly so the container can resolve Authentik at `portal.bytek.ca`.

### Nextcloud

Nextcloud containers must be able to resolve `portal.bytek.ca` for Authentik OIDC.

If the host resolves a name but the container does not, inspect the container’s Docker DNS configuration.

<div id="bkmrk--9" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Docker DNS Validation

Confirm a container’s configured DNS servers using:

`sudo docker inspect --format='DNS={{json .HostConfig.Dns}}' <container-name>`

Test hostname resolution from inside a container using:

`sudo docker exec <container-name> getent hosts portal.bytek.ca`

Expected internal result:

<div id="bkmrk-portal.bytek.ca-reso" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `portal.bytek.ca` resolves to `192.168.2.182`.

</div>If the command returns no output, container DNS is failing.

Do not change OIDC client IDs or secrets before DNS is proven healthy.

<div id="bkmrk--10" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Browser DNS Over HTTPS

Firefox-based browsers, including Zen, can bypass Pi-hole through DNS over HTTPS.

This previously prevented access to:

<div id="bkmrk-pve.bytek.ca" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `pve.bytek.ca`

</div>Pi-hole correctly resolved the private hostname, but Zen attempted to use protected public DNS instead.

Recommended setting:

<div id="bkmrk-dns-over-https%3A-off-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **DNS over HTTPS:** Off or Default Protection.

</div>If a private hostname works by IP but not by name:

<div id="bkmrk-check-the-hostname-f" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. Check the hostname from the operating system.
2. Query Pi-hole directly.
3. Disable forced browser DNS over HTTPS.
4. Clear the operating-system DNS cache.
5. Clear the browser DNS cache.
6. Close idle browser sockets.
7. Restart the browser.

</div>Useful Windows commands include:

<div id="bkmrk-resolve-dnsname-pve." style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `Resolve-DnsName pve.bytek.ca`
- `nslookup pve.bytek.ca 192.168.2.65`
- `Clear-DnsClientCache`
- `ipconfig /flushdns`

---

</div>## DNS Validation

### Test an Internal Application Record

Use:

`nslookup portal.bytek.ca 192.168.2.65`

Expected result:

<div id="bkmrk-portal.bytek.ca-reso-1" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `portal.bytek.ca` resolves to `192.168.2.182`.

</div>### Test Proxmox Resolution

Use:

`nslookup pve.bytek.ca 192.168.2.65`

Expected result:

<div id="bkmrk-pve.bytek.ca-resolve" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- `pve.bytek.ca` resolves to `192.168.2.254`.

</div>### Test Public Resolution

Use:

`nslookup google.com 192.168.2.65`

Expected result:

<div id="bkmrk-one-or-more-public-a" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- One or more public addresses are returned.

</div>### Test DNS Over TCP

Use:

`nc -zv -w 3 192.168.2.65 53`

### Test DNS Over UDP

Use:

`nc -zvu -w 3 192.168.2.65 53`

Both TCP and UDP DNS should be available to approved LAN clients.

<div id="bkmrk--11" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Service Health

Confirm that the Pi-hole LXC is running from Proxmox.

Confirm the guest address using:

`ip -br -4 addr`

Confirm DNS listeners using:

`ss -lntup | grep ':53'`

Confirm the Pi-hole DNS service using the appropriate service command for the installed Pi-hole version.

Review recent service logs if DNS queries fail.

<div id="bkmrk--12" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Management Access

Pi-hole management should remain private.

Approved access paths include:

<div id="bkmrk-home-lan.-trusted-re" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Home LAN.
- Trusted remote-access VPN.
- Proxmox console.
- SSH from an approved administrative source.

</div>Do not route Pi-hole administration through:

<div id="bkmrk-the-public-vps.-trae" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- The public VPS.
- Traefik public HTTPS.
- Authentik ForwardAuth.
- A public WHC hostname.
- Direct Bell router port forwarding.

---

</div>## Why Pi-hole Is Not Behind Authentik

Pi-hole is part of the dependency chain for internal Authentik and application resolution.

If Pi-hole management depended on Authentik, the following circular failure could occur:

<div id="bkmrk-pi-hole-dns-fails.-a" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. Pi-hole DNS fails.
2. Authentik’s hostname stops resolving internally.
3. Authentik login fails.
4. Pi-hole administration is protected by Authentik.
5. The administrator cannot reach Pi-hole to repair DNS.

</div>Pi-hole therefore uses local credentials and private network access.

<div id="bkmrk--13" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Upstream DNS

Pi-hole forwards non-local queries to configured upstream resolvers.

The chosen upstream resolver configuration should be documented after verification.

When changing upstream DNS:

<div id="bkmrk-record-the-current-c" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. Record the current configuration.
2. Change only one resolver setting at a time.
3. Test public DNS.
4. Test internal local records.
5. Test DNSSEC if enabled.
6. Test IPv4 and IPv6 behavior separately.
7. Confirm application containers still resolve external services.

</div>Do not assume that an upstream failure means Pi-hole itself is unavailable.

<div id="bkmrk--14" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## IPv6 Considerations

The Bytek homelab mainly uses IPv4 addressing.

If IPv6 is not intentionally configured end to end:

<div id="bkmrk-avoid-publishing-uni" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Avoid publishing unintended AAAA records.
- Verify clients are not receiving an unusable IPv6 DNS path.
- Check browser connection behavior.
- Check whether applications prefer IPv6 before IPv4.
- Document any intentional IPv6 disabling.

</div>An incorrect public AAAA record can cause clients to attempt an unavailable path before falling back to IPv4.

<div id="bkmrk--15" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Firewall Policy

Pi-hole must accept DNS from approved clients.

Typical requirements include:

<div id="bkmrk-lan-clients-to-tcp-5" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- LAN clients to TCP 53.
- LAN clients to UDP 53.
- Approved Docker hosts to TCP and UDP 53.
- Future VPN clients to TCP and UDP 53.
- Administrative SSH from approved LAN sources.
- Private management access from the LAN.

</div>Avoid exposing DNS publicly.

A publicly accessible recursive DNS resolver can be abused.

The Bell router must not forward public TCP or UDP port 53 to Pi-hole.

<div id="bkmrk--16" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Monitoring

Recommended Uptime Kuma monitors include:

<div id="bkmrk-monitor-target-pi-ho" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;"><div aria-expanded="false" class="___5wvz9a0 ftgm304 f1oy3dpc fm6nont f48hbct" data-stable-ignore="true" data-tabster="{"restorer":{"type":1}}" role="presentation" tabindex="0"><div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8"><table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg"><tbody><tr><th>Monitor</th><th>Target</th></tr><tr><td>Pi-hole guest</td><td>Ping `192.168.2.65`</td></tr><tr><td>Pi-hole DNS UDP</td><td>`192.168.2.65:53`</td></tr><tr><td>Pi-hole DNS TCP</td><td>`192.168.2.65:53`</td></tr><tr><td>Internal Authentik record</td><td>`portal.bytek.ca`</td></tr><tr><td>Internal Proxmox record</td><td>`pve.bytek.ca`</td></tr><tr><td>Public DNS resolution</td><td>Selected external hostname</td></tr></tbody></table>

</div></div></div>Monitoring should distinguish between:

<div id="bkmrk-guest-unavailable.-d" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Guest unavailable.
- DNS service unavailable.
- Internal records unavailable.
- Public forwarding unavailable.
- Upstream DNS unavailable.

---

</div>## Common Failure Scenarios

### Pi-hole Guest Is Down

Symptoms:

<div id="bkmrk-internal-hostnames-f" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Internal hostnames fail.
- Containers using Pi-hole cannot resolve names.
- Uptime Kuma reports several services down.
- Browser applications may fail internally.

</div>Check:

<div id="bkmrk-proxmox-guest-status" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Proxmox guest status.
- LXC startup.
- Guest network address.
- Pi-hole service.
- Backup availability.

</div>### Public DNS Fails but Local Records Work

Possible causes:

<div id="bkmrk-upstream-resolver-un" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Upstream resolver unavailable.
- Internet outage.
- DNSSEC issue.
- Firewall blocking outbound DNS.
- Incorrect upstream configuration.

</div>### Local Records Fail but Public DNS Works

Possible causes:

<div id="bkmrk-local-record-deleted" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Local record deleted.
- Typographical error.
- Different Pi-hole instance answering.
- Client using another DNS server.
- Browser DNS over HTTPS.
- Cached stale record.

</div>### VM Host Resolves but Container Does Not

Possible causes:

<div id="bkmrk-docker-embedded-dns-" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Docker embedded DNS issue.
- Container started before Pi-hole.
- Explicit Docker DNS is missing.
- Docker network is unhealthy.
- Guest firewall blocks DNS.

</div>Recovery may require recreating the container after Pi-hole is working.

### One Host Uses the Wrong Address

Possible causes:

<div id="bkmrk-client-dns-cache.-br" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Client DNS cache.
- Browser DNS cache.
- Forced DNS over HTTPS.
- Public resolver used instead of Pi-hole.
- Hosts-file override.
- Multiple active network adapters.
- VPN DNS override.

---

</div>## Power-Failure Recovery

After an electrical outage, Pi-hole should start before applications that depend on split DNS.

Recommended validation order:

<div id="bkmrk-confirm-proxmox-is-r" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. Confirm Proxmox is running.
2. Confirm the Pi-hole LXC started.
3. Confirm Pi-hole owns `192.168.2.65`.
4. Confirm TCP and UDP port 53.
5. Confirm one local record.
6. Confirm one public hostname.
7. Start or validate Traefik.
8. Validate Authentik.
9. Restart affected containers whose DNS remained broken.
10. Confirm Uptime Kuma monitors recover.

</div>Application containers may need to be recreated or restarted if Docker cached a broken DNS path during startup.

<div id="bkmrk--17" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Backup

The Pi-hole LXC is included in the Proxmox scheduled backup job.

The backup should preserve:

<div id="bkmrk-pi-hole-configuratio" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Pi-hole configuration.
- Local DNS records.
- DHCP reservations.
- Adlists.
- Allow and deny lists.
- Custom DNS settings.
- Network configuration.
- Administrative configuration.

</div>A Pi-hole configuration export may be maintained in addition to the Proxmox backup.

The export should be stored securely because it may contain internal network details.

<div id="bkmrk--18" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Recovery Procedure

If Pi-hole is unavailable:

<div id="bkmrk-open-proxmox-using-1" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. Open Proxmox using `192.168.2.254` if private DNS is unavailable.
2. Confirm the Pi-hole LXC is running.
3. Open the LXC console.
4. Confirm the interface owns `192.168.2.65`.
5. Confirm the default route.
6. Confirm TCP and UDP port 53.
7. Confirm the Pi-hole DNS service.
8. Test a local record from inside the LXC.
9. Test a public record.
10. Review logs.
11. Restore from a Proxmox backup if the configuration is damaged.

</div>If Pi-hole is restored under a temporary CT ID:

<div id="bkmrk-keep-the-restored-co" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Keep the restored container disconnected from the live LAN initially.
- Verify the configuration.
- Do not run two Pi-hole instances with the same IP.
- Shut down the failed instance before activating the restored one.

---

</div>## Address-Change Procedure

Changing Pi-hole’s address would affect most of the environment.

Before changing `192.168.2.65`:

<div id="bkmrk-document-the-current" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">1. Document the current state.
2. Update the Bell router or DHCP DNS settings.
3. Update Docker Compose files with explicit DNS.
4. Update Uptime Kuma.
5. Update future VPN client DNS.
6. Update firewall rules.
7. Update service documentation.
8. Flush client DNS caches.
9. Recreate containers that use explicit Docker DNS.
10. Test all split-DNS applications.

</div>Avoid changing Pi-hole’s address unless required.

<div id="bkmrk--19" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">---

</div>## Security Checklist

<div id="bkmrk-pi-hole-management-i" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Pi-hole management is LAN or VPN only.
- Public TCP and UDP port 53 are not forwarded.
- Local administrator credentials are stored securely.
- SSH uses key-based authentication.
- DNS access is limited to approved networks.
- Local DNS records contain only intended hostnames.
- Proxmox does not depend on Pi-hole.
- Pi-hole is not behind Authentik.
- Backups include the Pi-hole LXC.
- A configuration export exists or is planned.
- Browser DNS over HTTPS behavior is documented.
- Upstream DNS settings are documented.
- Recovery by private IP has been tested.

---

</div>## Validation Checklist

<div id="bkmrk-pi-hole-lxc-is-runni" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- Pi-hole LXC is running.
- Pi-hole owns `192.168.2.65`.
- TCP port 53 responds.
- UDP port 53 responds.
- Public names resolve.
- Internal hostnames resolve to Traefik.
- `pve.bytek.ca` resolves directly to Proxmox.
- No public WHC record exists for `pve.bytek.ca`.
- Traefik containers can use Pi-hole.
- Uptime Kuma can use Pi-hole.
- Nextcloud can resolve Authentik.
- BookStack can resolve Authentik.
- Vikunja can resolve Authentik.
- DNS over HTTPS is not bypassing Pi-hole on administrative browsers.
- Proxmox backup includes Pi-hole.

---

</div>## Document Control

<div id="bkmrk-owner%3A-bryan-gagne-p" style="font-family: 'Segoe UI'; font-size: 14px; font-style: normal; font-weight: 400; line-height: 20px;">- **Owner:** Bryan Gagne-Plante
- **Private address:** `192.168.2.65`
- **Primary role:** LAN DNS and split DNS
- **Secondary role:** DHCP reservations
- **Guest type:** LXC
- **Guest ID:** Confirm current CT ID
- **Management scope:** LAN or trusted VPN
- **Upstream resolvers:** Confirm current configuration
- **Last verified:** YYYY-MM-DD
- **Last DNS recovery test:** YYYY-MM-DD
- **Last backup test:** YYYY-MM-DD
- **Last configuration export:** YYYY-MM-DD
- **Known limitations:** Internal application resolution depends on one Pi-hole instance

</div>