Why Your Docker Containers Can't Resolve DNS: Fixing pfSense Unbound Timeouts

Fixing Periodic Docker Webhook Drops Caused by pfSense DNS Resolver (Unbound) Freezes

A comprehensive root cause analysis and step-by-step hardening guide for containerized services behind reverse proxies.

If you run containerized uptime monitors, alert dispatchers, or reverse-proxy stacks on a local server, you might run into an issue where outgoing notifications (such as Discord or Slack webhooks) suddenly stop firing. Inspecting the container logs often reveals failures like getaddrinfo ENOTFOUND or EAI_AGAIN.

A quick restart of the pfSense DNS Resolver (Unbound) usually restores connectivity immediately, but when this happens repeatedly every week or two, the root issue lies directly within how Unbound is processing queries.

Root Cause Analysis: What the Logs Show

Analyzing live Unbound logs when resolution drops reveals two hidden bottlenecks that interact to freeze the resolver service:

1. Excessive Debug Logging (Log Level ≥ 2)

What happens: The resolver writes dozens of granular trace messages (cache memory operations, module target iteration, module state transitions) per millisecond for every outbound query.

Why it breaks things: Disk and syslog I/O cannot keep up with high-frequency network queries. Unbound's single-threaded event loop blocks on write calls, causing incoming UDP DNS queries to time out and drop.

2. Iterative Root Recursion & Subquery Exhaustion

What happens: In pure resolver mode, pfSense manually walks every level of the global DNS tree (root . → TLD .com → authoritative nameservers → CNAME records) while validating multi-tiered DNSSEC cryptographic trust chains.

Why it breaks things: When any authoritative intermediate nameserver experiences packet loss or delays a response, Unbound logs event:module_event_noreply. The subqueries remain waiting in memory, worker threads pile up, and the service stops answering local LAN and Docker requests entirely.

Step-by-Step Fixes and Rationale

Step 1: Lower Logging Verbosity

• Go to Services > DNS Resolver > Advanced Settings.
• Set Log Level to Level 0 (or Level 1).
• Click Save and Apply Changes.

Why we do this: Eliminates continuous disk write contention and prevents syslog thread blocking. Unbound can process thousands of lookups in memory without pausing to flush trace lines to the firewall storage.

Step 2: Enable DNS Query Forwarding & Disable Redundant DNSSEC

• Go to Services > DNS Resolver > General Settings.
• Check Enable Forwarding Mode under DNS Query Forwarding.
• Uncheck DNSSEC.
• Click Save and Apply Changes.

Why we do this: Instead of pfSense querying 5 to 10 authoritative servers across the globe for every lookup, it delegates resolution to high-speed upstream anycast servers (Cloudflare, Google). These enterprise resolvers already validate DNSSEC and maintain massive global caches, drastically cutting query response times and bypassing subquery lockups completely.

Step 3: Define Upstream Resolvers and Disable ISP Overrides

• Go to System > General Setup.
• Add reliable upstream IPs under DNS Server Settings (e.g., 1.1.1.1 and 8.8.8.8), explicitly selecting your WAN Gateway.
• Uncheck DNS Server Override.
• Click Save.

Why we do this: Explicit gateway binding ensures DNS traffic always routes directly out of the active internet link. Unchecking "DNS Server Override" prevents your local ISP from pushing slower or less reliable DNS addresses during WAN DHCP lease renewals.

Step 4: Disable Dynamic DHCP Lease Registration

• Go to Services > DNS Resolver > General Settings.
• Scroll to the bottom and ensure DHCP Registration (Register DHCP leases in the DNS Resolver) is unchecked.
• Leave Static DHCP checked if you map local servers statically.
• Click Save and Apply Changes.

Why we do this: This is the most common cause of recurring Unbound crashes in pfSense. When enabled, pfSense completely reloads the Unbound service every single time a phone, laptop, or IoT device requests or renews an IP lease. On active networks, these constant restarts corrupt the cache or deadlock the process.

Step 5: Add Container-Level DNS Fallbacks

In your Docker Compose file, explicitly define upstream resolvers under the service definition:

services:
  monitoring-service:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: always

    # Provide direct DNS resolvers to ensure alerting never hangs on LAN DNS
    dns:
      - 1.1.1.1
      - 8.8.8.8

    networks:
      - web

Why we do this: Establishes defense-in-depth. If your internal router is ever rebooted, updated, or temporarily unreachable, your alert monitoring containers can still resolve external APIs and dispatch critical downtime notifications without interruption.

Expected Outcome: By turning off the DHCP restart loop, offloading recursive lookups to fast upstream forwarders, and removing excessive disk logging, Unbound maintains a lean in-memory cache and stops locking up. Internal hosts and containers will consistently resolve names without requiring manual firewall intervention.