Skip to content

DNS Resolution ​

DNS translates a service name into an IP address. In this homelab, UniFi supplies network settings through DHCP, Pi-hole filters and forwards DNS queries, and Nginx Proxy Manager (NPM) routes HTTPS requests to applications.

How a request reaches a service ​

text
Client receives DNS settings from UniFi DHCP
  → Pi-hole at 10.120.40.103 checks its cache and filtering rules
  → Uncached, permitted queries go to 1.1.1.1 or 1.0.0.1
  → Public DNS returns the service name's address

npm.home.rwk.me → home.rwk.me → 10.120.40.101
  → Client connects to NPM over HTTPS
  → NPM selects the application using the requested hostname

Cloudflare hosts the authoritative DNS for rwk.me. Cloudflare's recursive resolvers (1.1.1.1 and 1.0.0.1) are also Pi-hole's upstreams; these are separate roles. A cached answer can be returned without another upstream lookup.

The home.rwk.me records resolve through public DNS to NPM's private address, 10.120.40.101. Publishing that address does not make it reachable from the internet. Clients need access to the local network or an appropriate Tailscale route, and the connection must pass the network and application access controls.

Note

This setup does not require WAN port forwarding for the service names.

Configure the resolver ​

Set up the Pi-hole guest and follow the Pi-hole service guide for Docker configuration and persistent storage. Use 10.120.40.103 as its stable address and configure upstream DNS as 1.1.1.1;1.0.0.1.

UniFi remains the DHCP server. Pi-hole's DHCP server is disabled. This deployment has no conditional forwarding configured; do not assume Pi-hole can discover every DHCP client's hostname from UniFi. Pi-hole's local DNS domain is lan, while Default's DHCP domain is localdomain; neither setting creates the home.rwk.me service records.

In UniFi Network, edit each network's DHCP DNS settings:

NetworksDNS setting
Primary, IoT, Guests, Printers, Home Lab, ManagementManual: 10.120.40.103, with no secondary resolver
DefaultAutomatic; inspect the client's lease to see the DNS server supplied

Renew a client's DHCP lease after changing these settings. Devices with static network configuration need their DNS settings updated separately. For another homelab, substitute a reachable, stable resolver address and permit DNS across the required VLAN boundaries.

There is one Pi-hole resolver. If it is unavailable, new lookups that need it can fail even while cached answers or existing connections continue working. A public secondary resolver would let clients bypass filtering; use another managed resolver if DNS redundancy is needed.

Configure service names and HTTPS ​

  1. In your domain's DNS provider, create a DNS-only address record pointing to your proxy's private IP address. This homelab uses home.rwk.me pointing to 10.120.40.101; substitute your own domain and proxy address for another homelab.

  2. Add your service names as CNAME records targeting that record. This homelab uses names such as npm.home.rwk.me targeting home.rwk.me; use the equivalent names under your own domain.

    Note

    This homelab has a wildcard CNAME record in UniFi Network: *.home.rwk.me targets home.rwk.me. It handles all service hostnames under that domain without requiring a separate UniFi DNS record for each service.

  3. Create a matching proxy host in Nginx Proxy Manager, with the application's host address and published port as its upstream.

  4. Configure HTTPS using the guide's Cloudflare DNS challenge. DNS validation can issue certificates without exposing the application through WAN ports.

A DNS record only supplies an address. The proxy host, upstream application, certificate, and access policy must also be configured. Pi-hole local records are available for other local names; they are not required to reproduce this public-DNS service-name arrangement.

Docker names and remote clients ​

Containers on a shared Docker network can use service names such as sonarr or gluetun. That resolution is provided by Docker and is separate from Pi-hole. Those names do not automatically resolve on laptops, the Docker host, or containers on other networks. Use the service's domain or the host's published port from outside its Docker network.

Tailscale's node names and MagicDNS are also separate from application DNS. A remote client resolving home.rwk.me still needs the appropriate subnet route to reach the private address. Its resolver depends on its own DNS settings and the tailnet's DNS configuration.

Check resolution ​

From a trusted client with access to Pi-hole:

sh
dig @10.120.40.103 npm.home.rwk.me
dig @10.120.40.103 example.com
dig +tcp @10.120.40.103 npm.home.rwk.me
dig npm.home.rwk.me
curl -I https://npm.home.rwk.me

The service lookup should return the CNAME chain ending in 10.120.40.101. Compare the explicit Pi-hole lookup with the client's normal lookup to find a stale lease, static DNS setting, or different resolver. Check Pi-hole's query log to confirm the client is using it.

If DNS succeeds but HTTPS fails, check routing, firewall access, NPM's proxy host, and the application's health. If the address is stale, check the DNS record's TTL and client/browser caches. Browser secure DNS can use a different resolver; ordinary DNS and DNS-over-TLS port restrictions do not by themselves prevent DNS over HTTPS.

See the Network Overview, Pi-hole configuration, and NPM setup. Detailed policies and address assignments are in Firewall Policies · Internal and Network Allocation · Internal.

Reference: Pi-hole configuration.