Pi-hole

Purpose

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

Pi-hole is responsible for:

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.

Service Information

Architecture Role

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

When a LAN device opens a Bytek application:

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.

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:

Local Bytek Resolution

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

These local records create the split-DNS design.

Split-DNS Records

Application hostnames point internally to Traefik.

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

Public and Private DNS Comparison

The split-DNS model provides:

Proxmox DNS Exception

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

Proxmox uses:

This prevents the hypervisor from depending on a guest LXC for DNS.

As a result:

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.

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

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.

Why Stable Addresses Matter

Infrastructure addresses are referenced by:

An unexpected address change can break several services simultaneously.

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

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.

DNS Clients

Pi-hole may provide DNS to:

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.

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:

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:

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.

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:

If the command returns no output, container DNS is failing.

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

Browser DNS Over HTTPS

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

This previously prevented access to:

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

Recommended setting:

If a private hostname works by IP but not by name:

Useful Windows commands include:

DNS Validation

Test an Internal Application Record

Use:

nslookup portal.bytek.ca 192.168.2.65

Expected result:

Test Proxmox Resolution

Use:

nslookup pve.bytek.ca 192.168.2.65

Expected result:

Test Public Resolution

Use:

nslookup google.com 192.168.2.65

Expected result:

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.

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.

Management Access

Pi-hole management should remain private.

Approved access paths include:

Do not route Pi-hole administration through:

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:

Pi-hole therefore uses local credentials and private network access.

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:

Do not assume that an upstream failure means Pi-hole itself is unavailable.

IPv6 Considerations

The Bytek homelab mainly uses IPv4 addressing.

If IPv6 is not intentionally configured end to end:

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

Firewall Policy

Pi-hole must accept DNS from approved clients.

Typical requirements include:

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.

Monitoring

Recommended Uptime Kuma monitors include:

Monitoring should distinguish between:

Common Failure Scenarios

Pi-hole Guest Is Down

Symptoms:

Check:

Public DNS Fails but Local Records Work

Possible causes:

Local Records Fail but Public DNS Works

Possible causes:

VM Host Resolves but Container Does Not

Possible causes:

Recovery may require recreating the container after Pi-hole is working.

One Host Uses the Wrong Address

Possible causes:

Power-Failure Recovery

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

Recommended validation order:

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

Backup

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

The backup should preserve:

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.

Recovery Procedure

If Pi-hole is unavailable:

If Pi-hole is restored under a temporary CT ID:

Address-Change Procedure

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

Before changing 192.168.2.65:

Avoid changing Pi-hole’s address unless required.

Security Checklist

Validation Checklist

Document Control