Runbook: Configure WireGuard

1 · Prerequisites

Confirm every item is in place before any state change.

• WireGuard concept — kernel WireGuard, Noise protocol, UDP-based VPN
• WireGuard keys — Curve25519 key pairs, preshared key, key management
• WireGuard peers — named peers, allowed-ips, peer address and port, persistent keepalive
• WireGuard routing — routing over WireGuard, MTU 1420, MSS clamping
• WireGuard firewall and outer-packet routing — UDP port, input chain, multi-WAN
• MSS clamping — ip adjust-mss, MSS = MTU - 40, clamp-mss-to-pmtu, and which interface to clamp on
• commit-confirm — the rollback safety net for remote changes

2 · Pre-checks

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

• · Both ends of the tunnel are identified by name, by public WAN address, and by owner, and you have a working session on both. A tunnel configured from one side is not a tunnel; it is a route into a black hole.
• · Out-of-band access to this router is open and proved. Bringing a tunnel into service means committing a static route into it in the same change, and a route that swallows the prefix your management session arrives on takes the router with it.
• · The exact prefixes each side will reach through the tunnel are agreed in writing before any key is generated. These become allowed-ips on both ends and each list must be the mirror image of the other; a disagreement here produces silent one-way drops, not an error.
• · Neither set of prefixes overlaps anything either router already reaches — check with show ip route on both ends. The static route you will add for each prefix is a routing change riding inside a VPN ticket, and it wins or loses against the existing route on ordinary longest-prefix and administrative-distance rules.
• · The UDP listen port is agreed (51820 unless there is a reason) and confirmed reachable end to end: a firewall or a carrier-grade NAT in the path silently prevents the handshake and produces exactly the same symptom as a wrong key.
• · Which end sits behind NAT is established. That end needs persistent-keepalive and must be the one that initiates; the other end can leave the peer address unset.
• · A decision on the preshared key is recorded either way, with its owner. It is optional, it must be identical on both ends, and it is a second secret to distribute and rotate.
• · A secure channel exists to move public keys between the two operators. Public keys are not secret, but a key substituted in transit is an authenticated tunnel to the wrong router — read the fingerprint back over a second channel.
• · Pre-change configuration captured on both routers: show configuration commands | strip-private saved off-box, plus show ip route and show firewall ipv4 forward filter.
• · The MTU the tunnel will carry is decided in advance (1420 is the usual starting point for an IPv4 underlay) and there is a plan to measure it rather than assume it.

3 · Procedure

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

1. 1Open the out-of-band session on this router. Keep it open until the change is confirmed and saved.
2. 2Capture the baseline on both routers: show configuration commands | strip-private, show ip route, show interfaces. Save off-box.
3. 3Generate the key pair on each router separately — never generate both ends in one place. From configure mode: run generate pki wireguard key-pair install interface wg01, which assigns the private key to the interface and prints the public key.
4. 4Record each public key and read it back to the other operator over a second channel. Retrieve it later with show interfaces wireguard wg01 public-key.
5. 5If a preshared key is in scope, generate it once on one side only — generate pki wireguard preshared-key — and move it over a secret-bearing channel. Both ends must carry the identical value.
6. 6Build the interface on the far end first, including its peer entry for this router: address, port, and the agreed allowed-ips. A far end that is ready before this one is ready turns a half-finished change into a tunnel that simply has not come up yet, rather than a route into nothing.
7. 7Build the interface on this router: set interfaces wireguard wg01 address 10.255.255.1/30, set interfaces wireguard wg01 port 51820, set interfaces wireguard wg01 mtu 1420, set interfaces wireguard wg01 description SITE-B.
8. 8Add the peer, naming it for the site rather than for its key: set interfaces wireguard wg01 peer SITE-B public-key ..., ... peer SITE-B address 198.51.100.20, ... peer SITE-B port 51820, ... peer SITE-B allowed-ips 10.255.255.0/30, ... peer SITE-B allowed-ips 192.168.20.0/24. Add persistent-keepalive 25 on whichever end is behind NAT.
9. 9Add the routes, because allowed-ips does not: set protocols static route 192.168.20.0/24 interface wg01 for every far-side prefix. On VyOS allowed-ips is handed to wg set and nothing else — unlike wg-quick, the VyOS interface script installs no kernel route from it, so without this step the packet never reaches wg01 and the tunnel looks healthy while carrying nothing. The tunnel /30 needs no static route; it is connected from the interface address.
10. 10Open the underlay: set firewall ipv4 input filter rule 20 action accept, ... rule 20 protocol udp, ... rule 20 destination port 51820, ... rule 20 source address 198.51.100.20, ... rule 20 inbound-interface name eth0. Constrain it to the peer address; a WireGuard port open to the Internet is a scanning target that answers nothing but is still a target.
11. 11Permit the traffic that will now transit the tunnel: forward-chain rules naming wg01 in both directions, matching the prefixes agreed in the pre-checks. Routing the traffic and permitting it are two separate decisions and only one of them is allowed-ips.
12. 12Read the candidate before it goes live: compare. Check the allowed-ips list character by character against the written agreement, and check that no entry covers the prefix your management session arrives on.
13. 13Apply with commit-confirm 5. Treat the commit as capable of interrupting every peer already on this interface, not only the one being added.
14. 14Verify the handshake, which is the only liveness signal WireGuard has: show interfaces wireguard wg01 summary. The bare command without summary shows the link and its aggregate counters, not the peers. A peer that has never handshaked prints no latest handshake line at all, so you are checking that a line is present, not reading a status word.
15. 15Verify the data plane in both directions: ping the far tunnel address, then a host behind the far end, then have the far end do the same back. One-way success is the signature of an allowed-ips mismatch and must not be recorded as a pass.
16. 16confirm to cancel the rollback timer, then save on both routers.
17. 17Measure the usable MTU before declaring the tunnel finished: ping 192.168.20.10 size 1400 do-not-fragment, walking the size down until it succeeds. A tunnel that passes small pings and stalls on TLS is an MTU problem, and it will be reported as an application fault a week later.
18. 18Set MSS clamping from the measured result: set interfaces wireguard wg01 ip adjust-mss clamp-mss-to-pmtu, or an explicit value if the path needs one. Commit, confirm, save.
19. 19Record in the change ticket: both public keys, the agreed prefixes, the measured MTU, whether a preshared key is in use and where it is stored, and the rotation owner for the key material.

4 · Verification

Confirm the procedure actually fixed the problem.

• ✓show interfaces wireguard wg01 summary shows the peer with a recent latest handshake line and a transfer line with non-zero counts both ways. Peers appear there by base64 public key, not by the name you chose, because on 1.5 this subcommand prints wg show output verbatim. Interface state alone proves nothing — WireGuard interfaces come up whether or not any peer will ever answer.
• ✓Transfer counters are non-zero in both directions for that peer. Bytes sent with zero bytes received is the classic half-open tunnel: your packets are leaving, and the far end is discarding them or cannot reply.
• ✓show ip route 192.168.20.0/24 on this router resolves via wg01, and the mirror-image lookup on the far end resolves back via its own tunnel interface.
• ✓A host behind this router reaches a host behind the far router, and the reverse direction is tested independently by the far-end operator. Both directions, both operators, before the change is called done.
• ✓show firewall ipv4 input filter shows the UDP rule matching a non-zero packet count. A rule at zero after a successful handshake means the traffic is being accepted somewhere else, and the rule you think is protecting the port is not.
• ✓The allowed-ips on each end is the exact mirror of the other end, checked against the written agreement rather than against memory.
• ✓No static route added by this change covers the management prefix or the WAN prefix, and no allowed-ips entry covers them either — confirmed by reading show ip route after the commit, not by intent before it. The route is what can strand the session; the allowed-ips entry is what would encrypt that traffic to the wrong peer once a route existed.
• ✓A sized, do-not-fragment ping establishes the usable MTU, and MSS clamping is configured to match. A tunnel signed off on 64-byte pings has not been tested.
• ✓Existing peers on the same interface still show recent handshakes after the commit, if there were any.
• ✓Both routers are saved. A tunnel that survives only until the next reboot is worse than no tunnel, because it will be trusted.

5 · Rollback

If verification fails, undo the procedure in reverse order.

• ↶Inside the commit-confirm window with a router gone quiet: wait. The timer expires, the previous configuration returns, and no action is the correct action.
• ↶With a working session: rollback 1, then compare to read what it will undo, then commit. rollback alone loads the candidate and changes nothing until the commit.
• ↶Prefer the narrow revert, and remember it is two nodes. delete protocols static route 192.168.20.0/24 interface wg01 stops the router steering that prefix into the tunnel; delete interfaces wireguard wg01 peer SITE-B allowed-ips 192.168.20.0/24 stops WireGuard encrypting it to that peer and accepting it back. Removing only the allowed-ips entry leaves the route pointing at an interface that will now refuse the traffic. Deleting the whole interface to fix one prefix is how a second outage starts.
• ↶delete interfaces wireguard wg01 removes the tunnel entirely. Every flow using it drops at the commit, and every set protocols static route ... interface wg01 added by this change goes inactive with the interface — delete those too rather than leaving them behind pointing at nothing. This is the right move when the tunnel is actively harming traffic and the wrong move when it is merely not working yet.
• ↶POINT OF NO RETURN: a private key that has been generated, committed and distributed cannot be un-distributed. Rolling back the configuration does not un-tell the far end your public key, and it does not remove the private key from any configuration backup taken since the commit. If the key material is the reason for the rollback, treat it as a rotation, not a revert.
• ↶Rolling back this end alone leaves the far end holding a peer entry for a router that no longer answers. That is harmless for traffic but it is a stale trust relationship — tell the far-end operator, and have them remove the peer.
• ↶If a static route added by this change has already black-holed the management path, in-band rollback is not available and the console is the only route in. This is the failure commit-confirm exists for, and it is the reason the confirm window is set before the risky commit rather than after it.

6 · Escalation

When the runbook isn't enough, contact:

• · Escalate to the far-end operator, not to your own team, when the handshake never completes and the underlay is proved open from this side. Half the evidence lives on their router and no amount of work on yours will produce it.
• · Escalate to the network team when the underlay path traverses a carrier-grade NAT or a provider that filters UDP. A tunnel that cannot get its first handshake packet through is not a VyOS problem and will not be fixed by re-reading the configuration.
• · Escalate to security immediately if a private key may have been exposed — pasted into a ticket, mailed, left in an unencrypted configuration backup, or generated on a shared machine. The remedy is rotation on both ends, and it is a security decision about scope, not an operator decision about convenience.
• · Escalate to the service owner before adding an allowed-ips entry that overlaps a prefix the router already reaches by another path. That is a routing change wearing VPN clothes and it will move traffic that nobody asked to move.
• · Escalate to the application owner when the tunnel passes ping and fails TLS or file transfer. That signature is MTU, the fix is clamping, and the person seeing the failure needs to know it is not their application.
• · Escalate when a tunnel that was working stops after an unrelated commit on the same interface. Peers sharing an interface share its lifecycle, and that is a design question about how many peers belong on one WireGuard interface.

References

1. VyOS documentation — WireGuard
2. VyOS documentation — IPv4 firewall
3. VyOS documentation — Ethernet interface options (mtu, ip adjust-mss)
4. WireGuard — protocol and tooling
5. RFC 4821 — Packetization Layer Path MTU Discovery