Build a WireGuard Site-to-Site VPN

A site-to-site VPN joins two private subnets through dedicated gateways. Hosts on either side use ordinary LAN addresses; routing policy selects the traffic that crosses the encrypted tunnel.

Design decisions to make first

• The protected subnets must not overlap each other or the tunnel CIDR.
• Each gateway needs a stable reachable IPv4 address or DNS name.
• WAN interfaces must precede LAN interfaces so the generated mapping stays deterministic.
• Routers on each LAN need a route to the remote subnet through the VPN gateway.
• Firewalls must permit UDP 51820 between the public endpoints and the selected forwarding paths.

Deployable OpenFactory prompt

This prompt is intentionally a lab contract. It fixes every interface, subnet, selector, and assertion so OpenFactory can build and test the complete topology. Replace the WAN lab addresses before applying the resulting bundle in production.

Build and validate a Linux WireGuard site-to-site VPN named `branch-wireguard` as a BUILD_PLAN.

Create two `device_kind=linux-build` Debian Trixie gateways named `site-a-gateway` and `site-b-gateway`, each with the `headless`, `ssh`, and `vpn-wireguard` features plus tcpdump, iproute2, curl, and nftables. Site A has `172.31.220.10/24` on the shared `wan` network and `10.60.0.1/24` on `site-a-lan`. Site B has `172.31.220.20/24` on `wan` and `10.70.0.1/24` on `site-b-lan`. The WAN gateway is `172.31.220.1`, WAN is the only default-route network, and WAN must be the first interface on both gateways.

Create two additional `device_kind=linux-build` Debian Trixie computers with the `headless` and `ssh` features plus iproute2, iputils-ping, and curl. `site-a-computer` has one static interface, `10.60.0.10/24`, on `site-a-lan`; give it an `os.startup_scripts` oneshot named `remote-lan-route`, after `network-online.target`, that runs `ip route replace 10.70.0.0/24 via 10.60.0.1`. `site-b-computer` has one static interface, `10.70.0.10/24`, on `site-b-lan`; give it the same oneshot name, running `ip route replace 10.60.0.0/24 via 10.70.0.1`. Both computers must be separate recipes and topology nodes connected to their respective protected LANs.

Set `plan.vpn` to protocol `wireguard`, implementation `linux`, mode `site-to-site`, authentication `public-key`, tunnel CIDR `10.252.20.0/24`, listen port `51820`, and no clients. Site A's public endpoint is `172.31.220.10`, protected subnet is `10.60.0.0/24`, and connection type is `initiate`. Site B's public endpoint is `172.31.220.20`, protected subnet is `10.70.0.0/24`, and connection type is `respond`. Never put generated private keys in the BUILD_PLAN.

Add group assertions that `wg show wg0` succeeds on both gateways and that each peer configuration contains the other site's protected subnet. Add `command_output` assertions expecting `ready` that run `ip route get 10.70.0.10 | grep -q 'via 10.60.0.1' && ping -c 3 -W 5 10.70.0.10 >/dev/null && echo ready` on `site-a-computer`, and `ip route get 10.60.0.10 | grep -q 'via 10.70.0.1' && ping -c 3 -W 5 10.60.0.10 >/dev/null && echo ready` on `site-b-computer`. OpenFactory must generate distinct endpoint keys, apply both endpoint configs in the test VMs, prove traffic crosses between the two protected-LAN computers, and put the private deployment material in the owner-only bundle.

What OpenFactory builds

The topology uses two purpose-built Debian Trixie gateway images plus one Debian computer on each protected LAN. Each endpoint receives a unique private key, the remote public key, a tunnel address, and only the remote site's protected subnet in AllowedIPs. Private credentials are generated after the plan is accepted, outside the language-model response, and stored in an owner-only deployment ZIP.

The group test boots both endpoints and both LAN computers on the authored WAN and LAN networks, applies each endpoint's private files, and then runs topology assertions. The assertions confirm wg0 exists on both gateways, each endpoint has the other site's route, and the two LAN computers can ping across the tunnel in both directions.

The routing detail that decides whether it works

Each peer's AllowedIPs contains the remote tunnel address and the remote LAN prefix, never its own LAN. WireGuard uses that table for outbound peer selection and inbound source validation, as described in the official cryptokey-routing overview.

The LAN routers still need routes for the opposite site. Do not add masquerading between the protected subnets to hide a missing route; it discards useful source identity and makes policy review harder. During validation, inspect wg show, then send traffic to the remote tunnel address and confirm the latest handshake and byte counters advance.

A 1420-byte tunnel MTU is a common starting point, not a universal value. Test large TCP transfers and path-MTU discovery across the real WAN before rollout.

Production rollout

1. Download the private bundle and verify its manifest before moving files.
2. Replace lab WAN addresses with the real endpoints and confirm interface names.
3. Install only Site A files on Site A and only Site B files on Site B.
4. Add LAN routes for the remote protected subnet, or make the VPN gateway the relevant LAN router.
5. Open the required UDP ports and allow forwarding only between the declared selectors.
6. Test routing in both directions, MTU-sensitive traffic, tunnel recovery, and key or certificate rotation.

Compare this implementation with the Vyatta IKEv2/X.509 site-to-site guide, or use the road-warrior guide for individual roaming clients.