medium riskservice affecting~45 min

Runbook: Troubleshoot WireGuard

1 · Prerequisites

Confirm every item is in place before any state change.

WireGuard instance configured on OPNsense
Peer public key and endpoint address
SSH or console access to the firewall

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· Capture the current tunnel state from VPN > WireGuard > Status
· Identify the latest handshake timestamp for the failing peer
· Confirm the AllowedIPs on both sides do not conflict with existing routes
· Confirm the WAN-side firewall is not blocking UDP 51820 (or the configured port)

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Open VPN > WireGuard > Status and check the handshake time for the failing peer
2If the handshake timestamp is stale or absent, validate that the peer endpoint address and port are reachable from the WAN
3From the OPNsense shell, run wg show wg0 and confirm the peer entry shows the correct public key, endpoint, and allowed-ips
4Verify the local private key matches the public key configured on the remote peer (and vice versa)
5Check that AllowedIPs on the local side cover the remote subnet and inversely that the remote AllowedIPs cover the local subnet
6Inspect the firewall live log (Firewall > Log Files > Live View) on the WireGuard tab for blocks against the tunnel interface
7Add a temporary pass-any/any log rule on the WireGuard interface to confirm a rule problem versus a routing problem
8Restart the WireGuard instance (VPN > WireGuard > Status > Toggle) after a config change rather than reload via the GUI
9From a host on the local subnet, ping a host on the remote subnet and watch the handshake timestamp refresh

4 · Verification

Confirm the procedure actually fixed the problem.

✓The latest handshake timestamp is within the last 2 minutes
✓Transfer bytes counter on both peers increases when test traffic is sent
✓A bidirectional ping succeeds across the tunnel
✓Firewall live log shows permitted traffic on the WireGuard interface

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶Disable the failing WireGuard instance to drop traffic on the tunnel
↶Re-enable the previous configuration if a recent change is suspected
↶Revert the temporary pass-any rule added during debugging

6 · Escalation

When the runbook isn't enough, contact:

· If the handshake succeeds but traffic still fails, escalate to the network team with capture files from both endpoints
· If the WAN path is the suspected blocker, capture on the WAN interface to confirm whether UDP 51820 arrives
· If the remote peer is managed by a third party, engage the peer operator with the public key and AllowedIPs in hand

Purpose

Diagnose and restore a WireGuard site-to-site or road-warrior tunnel that is up but not passing traffic, or that is not establishing a handshake.

When to use this runbook

Use this runbook when a WireGuard tunnel used to work and is now broken, or when a new tunnel fails to come up. Scenarios include VPN > WireGuard > Status showing a stale handshake, transfer counters not increasing, or remote subnets being unreachable.

Pre-checks

Before starting the procedure, confirm the prerequisites and pre-checks are met. The structured lists are rendered from the frontmatter by the page layout.

Procedure

Follow the steps from the frontmatter procedure steps. The page layout renders the steps as a checklist with copy-to-clipboard affordances.

Verification

After the procedure, the structured verification items from the frontmatter are rendered as a checklist.

Rollback

If the procedure fails or makes things worse, follow the structured rollback steps from the frontmatter.

Escalation

The structured escalation path is rendered from the frontmatter. Use it if the operator cannot complete the procedure safely.