wg-backup/README.md

wg-relay

A WireGuard tunnel between two sites where the only thing reachable across it is one TCP port on one host per side.

ansible/
├── wg-relay.yml           # the whole thing
├── defaults.yml           # defaults
├── vars/
│   ├── site-a.yml         # Site A (Site B writes the mirror image)
│   └── site-b.yml
└── templates/
    ├── wg0.conf.j2
    ├── socat-relay.service.j2
    └── nftables-wgrelay.conf.j2

How it works

The relay VM never routes. ip_forward is pinned to 0 and the nftables forward chain policy is drop, so there is no path from the tunnel to the LAN. The only things listening are socat processes you declared:

• an inbound relay bound to the tunnel address, forwarding to one host:port on the local LAN
• an outbound relay bound to the LAN address, forwarding down the tunnel

Local clients point at the relay VM's LAN address and never learn a tunnel exists, so nothing on them needs reconfiguring if the relay changes.

Three layers have to agree before a packet gets anywhere:

1. WireGuard — AllowedIPs is a /32, which the kernel enforces as a source filter. A peer that forges a source address outside its own /32 is dropped before any userspace sees it.
2. nftables — the tunnel interface ends in an explicit drop; only the declared relay ports, from the declared source, get through.
3. socat — forwards to exactly one host:port, running as nobody.

Each side's restrictions live entirely on its own machine. There is no mechanism for one site to prove to the other how its half is configured — and none is needed, since the half that protects you is the half you control.

Prerequisites

You can use the ansible repositories or another installation method if desired, all that matters is you have ansible

Needs ansible-core, no other packages or collections are needed. The playbook will install additional required packages

sudo apt update && sudo apt install ansible

Setup

The playbook and defaults.yml are identical at both sites. Everything that differs lives in that site's vars file — copy vars/site-a.yml and edit:

• relay_host / relay_user — which box to configure. Set it to the relay VM to run over SSH, or leave it as localhost to configure the machine you're sitting on.
• wg_address — this side's tunnel address, as a /32.
• wg_peers — the other site's public key, endpoint and /32.
• relays — the inbound and outbound listeners.

Values in the vars file override defaults.yml, because -e outranks everything else. Adding a site later means one more file in vars/; the playbook doesn't change.

Installation

Run it at each site against that site's vars file. No inventory file needed.

ansible-playbook wg-relay.yml -e @vars/site-a.yml --check --diff
ansible-playbook wg-relay.yml -e @vars/site-a.yml

Leave the peer's public key as the placeholder on the first run — it generates a keypair and prints this side's public key. Exchange public keys, fill in wg_peers[].public_key in each vars file, then run again. Finally, point the local client at the relay VM's LAN address and port.

Each run ends by asserting forwarding is off, waiting for each relay port to accept connections, and printing wg show.

Notes

• The wg0.conf task is no_log: true because the file contains the private key; --diff won't show it changing. That's deliberate.
• Keys live in /etc/wireguard/private.key (0600, root-only). To manage them centrally instead, set wg_private_key from Ansible Vault and the playbook skips generation.
• Removing a relay from the vars file stops and deletes its systemd unit on the next run — no orphaned listeners.
• If either uplink is PPPoE or tunnelled, drop wg_mtu to 1380. Sustained bulk transfers are what find PMTU blackholes, and the symptom is a stall mid-transfer rather than a clean failure.
• socat_group: nogroup is Debian/Ubuntu. On RHEL-family set it to nobody.
• Whichever side is behind CGNAT should omit endpoint and let the other side dial in; PersistentKeepalive holds the path open. If both sides are behind CGNAT, neither can reach the other directly and this design doesn't apply as-is.
• The relay is TCP only. A UDP service needs UDP-LISTEN/UDP in the socat unit and a matching udp dport rule in the nftables template.
• Protocols that embed their own hostname or redirect clients to a second address (anything doing virtual-host-style routing) need that address to resolve on the client side too — a relay changes the address clients connect to, and some protocols notice.