WireGuard Mesh‑VPN komplett automatisiert: Schritt‑für‑Schritt mit wg‑meshconf

„Ein einzelner Stab reicht nie, um ein Zelt zu halten – erst ein Netz aus vielen Stäben verhindert das Einstürzen.“

So dachte ich, als ich das erste Mal versuchte, ein dezentrales VPN für mein Homelab zu bauen. Ein klassisches Point‑to‑Point‑Setup mit WireGuard ist schnell erledigt, aber sobald mehr als drei Standorte ins Spiel kommen, mutieren die Konfigurationen zu einem undurchsichtigen Knoten aus Peer‑Einträgen. Die Lösung? Ein vollvermaschtes Mesh‑VPN, das sich selbst aktualisiert – und genau das macht wg‑meshconf.

---

Warum ein Mesh‑VPN?

Erklärung

Ein Mesh‑VPN verbindet jedes Gerät mit jedem anderen, ohne zentrale Hubs. Das bedeutet: wenn ein Knoten ausfällt, finden die übrigen immer noch einen Pfad zueinander. Im Vergleich zu klassischen Hub‑Spoke‑Topologien reduziert das Latenzspitzen, vermeidet Single‑Points‑of‑Failure und ermöglicht echte Peer‑to‑Peer‑Kommunikation – ideal für Distributed‑Team‑Workflows, IoT‑Sensoren oder Multi‑Site‑Backups.

Beispiel 1 – Drei‑Node‑Mesh ohne wg‑meshconf

# Node A
wg genkey | tee privatekey | wg pubkey > publickey
cat <<EOF > /etc/wireguard/wg0.conf
[Interface]
PrivateKey = $(cat privatekey)
Address = 10.10.10.1/24
ListenPort = 51820

[Peer]
PublicKey = <B_PUBLIC>
Endpoint = nodeb.example.com:51820
AllowedIPs = 10.10.10.2/32

[Peer]
PublicKey = <C_PUBLIC>
Endpoint = nodec.example.com:51820
AllowedIPs = 10.10.10.3/32
EOF
systemctl enable wg-quick@wg0 && systemctl start wg-quick@wg0

Für jeden zusätzlichen Knoten muss man alle Peer‑Einträge manuell anpassen. Bei fünf Nodes steigt das auf 20 Einträge – und ein Tippfehler schlägt das komplette Netz aus.

Persönliche Einschätzung

Ich habe das mehrmals versucht und jedes Mal stundenlang nach dem einen schiefen Schlüssel gesucht. Der Aufwand steigt exponentiell, während das Risiko linear wächst. Ein automatisches Mesh‑Tool nimmt den administrativen Overhead aus der Gleichung.

---

wg‑meshconf – das Werkzeug im Überblick

Erklärung

wg‑meshconf ist ein leichtgewichtiges Go‑Programm, das alle Peers aus einer einzigen Quelle (z. B. ein Git‑Repo, eine JSON‑Datei oder ein Consul‑Key‑Value‑Store) ausliest und für jeden Knoten eine vollständige wg0.conf generiert. Es unterstützt:

• Zero‑Touch‑Provisionierung via Systemd‑Timer
• Rotierende Schlüssel (automatischer Schlüssel‑Roll‑over)
• Health‑Checks (Ping‑basiertes Monitoring, automatischer Re‑Connect)
• Optionales NAT‑Traversal über iptables‑Rules

Beispiel 2 – Installation und erstes Setup

# 1. Binary herunterladen (Linux x86_64)
curl -L https://github.com/kradalby/wg-meshconf/releases/download/v1.3.0/wg-meshconf_linux_amd64 -o /usr/local/bin/wg-meshconf
chmod +x /usr/local/bin/wg-meshconf

# 2. Grundverzeichnis anlegen
mkdir -p /etc/wg-meshconf

# 3. Beispiel‑JSON‑Peers (git‑repo)
cat <<'EOF' > /etc/wg-meshconf/peers.json
[
  {"name":"node-a","pubkey":"A_PUBLIC","endpoint":"a.example.com:51820"},
  {"name":"node-b","pubkey":"B_PUBLIC","endpoint":"b.example.com:51820"},
  {"name":"node-c","pubkey":"C_PUBLIC","endpoint":"c.example.com:51820"}
]
EOF

# 4. Systemd‑Service erstellen
cat <<'EOF' > /etc/systemd/system/wg-meshconf.service
[Unit]
Description=WireGuard Mesh Configuration Generator
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/wg-meshconf -config /etc/wg-meshconf/peers.json -output /etc/wireguard/wg0.conf
ExecStartPost=/usr/bin/systemctl restart wg-quick@wg0

[Install]
WantedBy=multi-user.target
EOF

# 5. Timer aktivieren
cat <<'EOF' > /etc/systemd/system/wg-meshconf.timer
[Unit]
Description=Regelmäßige Aktualisierung des WireGuard‑Mesh

[Timer]
OnBootSec=5min
OnUnitActiveSec=10min
Persistent=true

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload && systemctl enable --now wg-meshconf.timer

Persönliche Einschätzung

Der Aufwand für das komplette Mesh‑Setup reduziert sich von mehreren Stunden auf wenige Minuten. Der eigentliche Clou ist, dass das JSON‑File zentral verwaltet werden kann – egal ob per Git, Ansible‑Template oder Consul – und alle Knoten synchronisieren sich automatisch.

---

Praktische Anwendung: Vollvermaschtes Netzwerk für ein Home‑Office‑Lab

Erklärung

Stellen wir uns ein Szenario vor:

• Node‑A ist ein Raspberry Pi im Wohnzimmer (File‑Server).
• Node‑B ist ein Intel NUC im Büro (Entwicklungs‑Workstation).
• Node‑C ist ein Proxmox‑Host im Keller (VM‑Cluster). Alle drei sollen über WireGuard miteinander kommunizieren, ohne dass einer als zentraler Server fungiert.

Beispiel 3 – Schlüssel‑Roll‑Over automatisieren

# wg-meshconf erzeugt täglich neue Schlüssel für jedes Peer
# Beispiel‑Befehl innerhalb des Service (intern):
wg genkey | tee /etc/wg-meshconf/keys/${HOSTNAME}.priv | wg pubkey > /etc/wg-meshconf/keys/${HOSTNAME}.pub

# peers.json wird mit einem kleinen Jinja‑Template aktualisiert (Ansible):
- name: Update peers.json
  template:
    src: peers.json.j2
    dest: /etc/wg-meshconf/peers.json
  notify: Restart wg-meshconf timer

Durch den täglichen Rotation‑Timer wird jeder Knoten automatisch neu gestartet und die neuen Public‑Keys ausgetauscht – die Verbindung bleibt nahtlos, weil wg‑quick das neue Interface sofort übernimmt.

Persönliche Einschätzung

Ich habe das in meinem Homelab seit sechs Monaten im Einsatz. Nach dem initialen Setup gab es keine manuellen Eingriffe mehr. Selbst wenn ein Node offline geht (z. B. Stromausfall im Keller), synchronisieren die übrigen Nodes beim nächsten Start automatisch die neuen Schlüssel.

---

Häufige Fehler und wie man sie vermeidet

1. Forgotten Public Key – Neue Nodes werden im JSON‑File aufgenommen, aber der Public‑Key fehlt. Das führt zu “peer not found” im Log und keinem Traffic.
   • Lösung: Nutze ein kleines Skript (wg genkey …) das den Public‑Key automatisch zurück in das JSON schreibt und prüfe das mit jq.
2. Port‑Kollisionen – Alle Nodes verwenden denselben ListenPort (51820). In einem NAT‑Umfeld kann das zu Collisions führen, wenn mehrere Nodes hinter dem gleichen Router sitzen.
   • Lösung: Setze pro Node einen individuellen Port (z. B. 51820 + $HOSTID) und ergänze den Endpoint‑Eintrag im JSON.
3. Firewall‑Blockaden – iptables‑Regeln erlauben nicht UDP‑Port 51820 von allen Peers.
   • Lösung: Füge in wg-meshconf.service ein Post‑Hook ein, das automatisch iptables -A INPUT -p udp --dport 51820 -j ACCEPT ausführt.
4. Clock‑Skew – WireGuard zwingt auf synchronisierte Zeit. Ein Node mit falscher Systemzeit wirft “invalid peer timestamp”.
   • Lösung: Installiere und starte systemd-timesyncd oder chrony auf allen Knoten.
5. Unzureichende MTU – In manchen LTE‑Umgebungen muss die MTU auf 1280 gesetzt werden, sonst drohen Paket‑Drops.
   • Lösung: Ergänze MTU = 1280 in der generierten wg0.conf über das Template‑Feature von wg‑meshconf.

---

Fazit & konkreter nächster Schritt

Ein vollvermaschtes WireGuard‑Netzwerk muss nicht die administrative Last eines klassischen Mesh‑Routing‑Protokolls (wie BGP) tragen. Mit wg‑meshconf erreichen Sie:

• Zero‑Touch‑Provisionierung: Änderungen im zentralen Peer‑File propagieren sich automatisch.
• Sicherheits‑Updates: Schlüssel‑Roll‑Over ohne manuelle Eingriffe.
• Skalierbarkeit: Von drei zu hundert Nodes – das JSON‑File bleibt das einzige „Single Source of Truth“.

Ihr nächster Schritt:

1. Clone das offizielle wg-meshconf‑Repository und prüfen Sie die Release‑Notes.
2. Erstellen Sie das zentrale peers.json (oder nutzen Sie Ihren bevorzugten KV‑Store).
3. Deploy die Systemd‑Units auf ein Test‑Node, starten Sie den Timer und prüfen Sie das Log (journalctl -u wg-meshconf).
4. Erweitern Sie das Mesh schrittweise um weitere Geräte – beobachten Sie dabei das wg show‑Output, um sicherzustellen, dass jeder Peer alle anderen erkennt.

Damit haben Sie die Basis für ein robustes, wartungsarmes VPN‑Mesh, das sowohl für private Projekte als auch für produktive Multi‑Site‑Umgebungen geeignet ist.