Runbook: Configure WireGuard

Purpose

This runbook stands up a WireGuard tunnel on OPNsense for either site-to-site or remote-access use, including key generation, peer configuration, interface assignment, firewall rules, and a verified handshake. It is the runbook to reach for whenever an encrypted tunnel is needed between OPNsense and a peer (a remote site, a branch, a remote-access client, or a cloud VPC).

When to use this runbook

Use this runbook when a new WireGuard tunnel is being established. It assumes the topology decision (site-to-site vs remote-access) and the IP plan (tunnel addresses and routed subnets) have already been made and approved in the change record.

Pre-checks

• Capture a fresh encrypted config backup before any change.
• Confirm UDP 51820 (or the chosen port) is open on any upstream firewall / ISP for both endpoints.
• Confirm the tunnel subnet does not overlap with any existing subnet on OPNsense or the peer.
• Exchange public keys with the peer out of band; do not transmit private keys over the same channel that will carry the tunnel.
• Decide site-to-site vs remote-access topology and document routed subnets in the change record.

Procedure

1. Install the WireGuard plugin. System > Firmware > Plugins > search os-wireguard > + > confirm. Refresh the GUI; VPN > WireGuard now appears.
2. Enable the WireGuard service. VPN > WireGuard > enable > set a generic listen port (default 51820) > Save. Apply.
3. Add a local instance. VPN > WireGuard > Local > +. Set Name (e.g. wg_s2s_hq). Leave Public Key blank — OPNsense will generate one. Click + next to Private Key to generate it; the matching public key is revealed. Copy the public key to share with the peer.
4. Configure the local instance. Set Listen Port to 51820 (or chosen port). Set Tunnel Address to the OPNsense tunnel IP with /32 (e.g. 10.10.10.1/32). Leave Disable Routes off unless the peer will advertise routes through this tunnel; for site-to-site, leave it off and add explicit routes later. Save.
5. Add the peer. VPN > WireGuard > Peers > +. Set Name (e.g. peer_branch01). Paste the peer’s Public Key. Set Pre-shared Key if using PSK mode (recommended for site-to-site).
6. Configure peer allowed IPs. Set Allowed IPs to include the peer’s tunnel address AND any subnets the peer routes through the tunnel (e.g. 10.10.10.2/32, 10.20.0.0/24). This field is symmetric: it defines what OPNsense will route into the tunnel.
7. Set the peer endpoint. Endpoint Address to the peer’s public IP or hostname, Endpoint Port to the peer’s listen port. Leave blank for a remote-access peer that may roam (the peer initiates).
8. Set keepalive. Persistent Keepalive to 25 (seconds) for NAT-traversal / mobile clients; 0 or omit for site-to-site on stable endpoints. Save and apply.
9. Assign the WireGuard interface. Interfaces > Assignments > pick the new wg_s2s_hq interface from the dropdown > + > Save.
10. Configure the WireGuard OPT interface. Click the new OPT entry. Check Enable interface. Set IPv4 configuration type to Static IPv4 and enter the same tunnel IP with /32. Set MTU to 1420 to avoid fragmentation over most paths. Save and Apply.
11. Add firewall rules on the WireGuard interface. At minimum, allow from the tunnel subnet to the LAN subnet(s) you want to route to (and vice versa if you need peer-side access). Default deny at the bottom catches anything else.
12. Outbound NAT if the peer needs internet via OPNsense. Firewall > NAT > Outbound (Hybrid mode) > add a rule mapping the peer’s subnet to the WAN address. Otherwise the return path from internet-bound traffic is unmatched.
13. Configure the peer. On the peer device, install WireGuard, paste the local public key as the peer entry, set Allowed IPs to include OPNsense’s tunnel address and routed subnets, set Endpoint to OPNsense_public_IP:51820, and bring the interface up.
14. Verify the handshake. On OPNsense, from Diagnostics > Command Prompt, run wg show. Confirm the peer appears with a latest handshake timestamp within the last 2 minutes.
15. Test reachability. From Diagnostics > Ping, ping the peer’s tunnel address. Success indicates the tunnel is up end-to-end. From the peer, ping OPNsense’s tunnel address back.

Verification

• wg show on OPNsense lists the peer with a latest handshake within the last 2 minutes.
• wg show on the peer lists OPNsense with a matching latest handshake.
• Ping from OPNsense to the peer’s tunnel address succeeds.
• Ping from the peer to OPNsense’s tunnel address succeeds.
• Hosts on either side of the tunnel can reach hosts on the other side (firewall rules permitting).
• ifconfig <wg_if> on OPNsense shows the tunnel IP and status: active.

Rollback

• Delete the peer entry on VPN > WireGuard > Peers and Save.
• Disable and remove the WireGuard interface assignment.
• Disable the WireGuard instance on VPN > WireGuard > Local.
• Restore the pre-change encrypted config backup if alias or other related changes were made.
• On the peer device, shut down the WireGuard interface.
• Confirm OPNsense and the peer no longer show the tunnel in their routing tables.

Escalation

• Escalate to the network team if the handshake never completes: check UDP 51820 is open on both ends, no ISP is blocking the port, and the public keys are not swapped.
• Escalate to the platform team if the WireGuard kernel module fails to load; check the plugin version matches OPNsense 25.x and that no custom kernel modules are conflicting.
• Escalate to the application owner if specific traffic over the tunnel is dropped; suspect MTU (lower to 1380), MSS clamping on TCP, or a firewall rule on either side.
• Escalate to security if the routed subnets cross trust boundaries without a documented exception; require a change record approval before allowing tunnel access to production segments.