Skip to main content
RunBook Academy

← All break/fix scenarios in OPNsense

intermediateNetworking~25 min

Break/Fix: VPN Tunnel Up But DNS Resolution Fails

Reported symptoms

  • ●Remote users can ping by IP but cannot resolve internal names
  • ●Web services on the remote side fail with "host not found"
  • ●Local LAN clients work normally

Evidence

  • · WireGuard peer shows recent handshake and live transfer
  • · dig @10.0.1.1 internal.corp.local returns SERVFAIL or times out
  • · Unbound ACL does not list the WireGuard tunnel subnet (10.10.0.0/24)
Diagnosis and resolutionclick to reveal

Root cause

Unbound is configured to only answer DNS for known local subnets. The tunnel subnet is missing from the ACL, so DNS queries from remote clients are refused or silently dropped before they reach the resolver.

Remediation

1. Add the WireGuard tunnel subnet to Unbound's access list under Services → Unbound DNS → Access Lists. 2. Confirm a "Allow" rule on the WireGuard interface permits UDP/53 to the firewall's tunnel address. 3. Apply and re-test.

Verification

Remote client successfully resolves internal.corp.local via the tunnel; Unbound query log shows queries sourced from the tunnel subnet.

Prevention

Any time a new tunnel subnet is added, extend Unbound's ACL and add a DNS rule on the tunnel interface in the same change. Treat DNS as part of the tunnel definition, not as a separate service.

Scenario

You are operating an OPNsense edge with a WireGuard remote-access tunnel. The following symptoms appear:

  • Remote users can ping by IP but cannot resolve internal names
  • Web services on the remote side fail with “host not found”
  • Local LAN clients work normally

Available evidence:

  • WireGuard peer shows recent handshake and live transfer
  • dig @10.0.1.1 internal.corp.local returns SERVFAIL or times out
  • Unbound ACL does not list the WireGuard tunnel subnet (10.10.0.0/24)

Your task

Determine the cause, recover, document, and validate.

Investigation

The investigation follows the discipline taught in Part XXIII:

  1. Form hypothesis, find evidence, test, validate.
  2. Use the available evidence above to bound the search.
  3. Reach one of the likely root causes.

Recovery procedure

(Do not reveal until you have reasoned through the problem.)

  1. Identify the failing component.
  2. Apply the remediation pathway.
  3. Validate with the verification step.
  4. Document the incident.

Remediation

  1. Add the WireGuard tunnel subnet to Unbound’s access list under Services → Unbound DNS → Access Lists. 2. Confirm a “Allow” rule on the WireGuard interface permits UDP/53 to the firewall’s tunnel address. 3. Apply and re-test.

Verification

Remote client successfully resolves internal.corp.local via the tunnel; Unbound query log shows queries sourced from the tunnel subnet.

Rollback

Remove the new ACL entry and the WireGuard DNS rule.

Prevention

Any time a new tunnel subnet is added, extend Unbound’s ACL and add a DNS rule on the tunnel interface in the same change. Treat DNS as part of the tunnel definition, not as a separate service.