Ansible Rolle - WireGuard Site-to-Site VPN

Rolle zur Bereitstellung von WireGuard Site-to-Site VPN-Setups.

Molecule Logs: Kurz, Voll

Getestet:

• Debian 11
• Raspbian 11
• Debian 12

Installation

# zuletzt
ansible-galaxy role install git+https://github.com/ansibleguy/infra_wireguard

# aus der Galaxy
ansible-galaxy install ansibleguy.infra_wireguard

# oder in einen benutzerdefinierten Rollen-Pfad
ansible-galaxy install ansibleguy.infra_wireguard --roles-path ./roles

# Abhängigkeiten installieren
ansible-galaxy install -r requirements.yml
python3 -m pip install -r requirements.txt

---

Mitwirken

Fühlen Sie sich frei zu:

• PRs öffnen

• Diskussionen starten

• Probleme eröffnen => nachdem Sie das Troubleshooting-Guide unten überprüft haben!

---

Nutzung

Möchten Sie eine einfache Ansible GUI? Schauen Sie sich meine Ansible WebUI an.

Beispiele

Hier einige detaillierte Konfigurationsbeispiele und deren Ergebnisse:

• Topologie - Einfach
• Topologie - Stern
• Topologie - Mesh

Konfiguration

Sie können Ihre WireGuard-Topologien definieren, die sich über mehrere Hosts oder Host-Gruppen erstrecken.

Die Rolle filtert die Topologien, die zum aktuellen Ziel-Host gehören, und konfiguriert diese.

Diese Peer-Keys müssen mit den Hostnamen in Ihrer Ansible-Inventarliste übereinstimmen!

wireguard:
  restart_on_change: true  # Erlaubt das Neustarten der wg-Services bei Änderungen

  topologies:
    dc_nl:
      type: 'einfach'
      peers:
        srv02:
          Endpoint: 'srv02.wg.template.ansibleguy.net'
          Address: '10.100.0.1/30'

        srv03:
          Endpoint: 'srv03.wg.template.ansibleguy.net'
          Address: '10.100.0.2/30'

Sie möchten möglicherweise 'ansible-vault' verwenden, um die Host-Key-Dateien zu verschlüsseln:

ansible-vault encrypt roles/ansibleguy.infra_wireguard/files/keys/some_file.key

Ausführung

Führen Sie das Playbook aus:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml

Oder wenn Sie Ihre Schlüssel verschlüsselt haben:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml --ask-vault-pass

Es sind auch einige nützliche Tags verfügbar:

• basis
• konfiguration
• tunneln
• löschen

Wenn Sie nur eine Ihrer Topologien bereitstellen möchten, können Sie die folgende Variable zur Ausführungszeit setzen:

ansible-playbook -K -D -i inventory/hosts.yml playbook.yml -e only_topo=TOPOLOGY_KEY

---

Funktionalität

• Paketinstallation

  • WireGuard
  • Resolvconf (Namensauflösung)

• Konfiguration

  • Vereinfachte Konfiguration durch die Zuordnung von Topologien

  • Unterstützte Topologien:

    • einfach - einfach zwei Knoten verbinden
    • stern - mehrere Rand-/Zweigknoten verbinden sich mit einem zentralen Hub
    • mesh - jeden Peer mit jedem anderen verbinden

  • Schlüssel

    • Generierung von öffentlichen/privaten Schlüsselpaaren für jeden Host in einer Topologie (WG identifiziert Peer durch publicKey)
    • Schlüssel werden zum Controller geschrieben für Konsistenz

  • Routing

    • Das Routing liegt in Ihrer Verantwortung! Sie können die automatisch hinzugefügten WG-Routen aktivieren oder benutzerdefinierte Up-/Down-Skripte hinzufügen.

  • Standardkonfiguration:

    • Speichern des privaten Schlüssels in einer Datei
    • Deaktivierung der automatischen Routenhinzufügung (um Sperren zu vermeiden & Anpassungen zu ermöglichen)
    • Aktivierung von Syslog-Protokollierung mit Instanz-Identifiers
    • Neustart des wg-Services bei Änderungen

  • Standard-Opt-ins:

    • Verwendung von PSK für zusätzliche Sicherheit
    • Löschen von verwaisten Tunneln

  • Standard-Opt-outs:

    • Installation von 'resolvconf' für die Namensauflösung
    • Traffic-Weiterleitung (router-ähnlich)

  • Funktionen:

    • Anzeigen der letzten Protokolle, wenn der Dienst neu gestartet wird
    • Automatisches Verbinden von dynamischen Peers

---

Infos

• Hinweis: Diese Rolle unterstützt derzeit nur debian-basierte Systeme.

• Hinweis: Die meisten Funktionen der Rolle können ein- oder ausgeschaltet werden.

  Für alle verfügbaren Optionen - siehe die Standardkonfiguration in der Haupt-Standarddatei!

• Warnung: Nicht jede Einstellung/Variable, die Sie angeben, wird auf Gültigkeit überprüft. Eine schlechte Konfiguration kann die Rolle beeinträchtigen!

• Warnung: Beachten Sie, dass die WireGuard Up-/Down-Skripte ausgeführt werden, wenn der TUNNEL-DIENST hochfährt; NICHT DIE TUNNELVERBINDUNG.

  Dies sollten Sie bei der Planung/Konfiguration Ihrer Routen und Metriken berücksichtigen!

• Info: Halten Sie Ihre Topologienamen kurz. Versuchen Sie, keine Sonderzeichen zu verwenden => sie werden automatisch entfernt (außer '_=+.-'), damit der Schlüssel ein gültiger Schnittstellennamen ist!

• Info: Schnittstellen erhalten ein Präfix:

  • einfach => wgs_
  • stern => wgx_
  • mesh => wgm_

• Info: Wie man Tests ausführt, ist hier beschrieben.

• Info: Die Host-Keys werden standardmäßig im Verzeichnis 'files' der Rolle gespeichert.

  Dieses Verzeichnis kann über die Variable 'controller_key_store' geändert werden!

• Info: Wenn Sie OPNSense Firewalls verwenden - können Sie die ansibleguy.opnsense Ansible-Sammlung verwenden, um diese WireGuard-Tunnel zu verwalten.

---

Fehlerbehebung

Wenn Sie auf Verbindungsprobleme stoßen => bitte folgen Sie diesen Schritten, um die Quelle einzugrenzen:

1. Ist das VPN aktiv?

wg show all

Wenn nicht:

• Die Verbindung kann nicht hergestellt werden - möglicherweise eine Fehlkonfiguration oder ein Netzwerkproblem (Firewall blockiert den Verkehr)

• Überprüfen Sie Ihre WireGuard-Protokolle:

  # 'wgs_ts2' ist das WireGuard-Tunnel-Interface in diesem Beispiel
  guy@srv:~# journalctl -u wg-quick@wgs_ts2
  > -- Protokoll beginnt am Tue 2022-02-08 15:46:07 UTC, endet am Tue 2022-02-08 17:01:27 UTC. --
  > Feb 08 16:12:31 test-ag-wg-s3 systemd[1]: Starte WireGuard über wg-quick(8) für wgs_ts2...
  > Feb 08 16:12:31 test-ag-wg-s3 wireguard_wgs_ts2[10698]: [#] ip link add wgs_ts2 type wireguard
  > Feb 08 16:12:31 test-ag-wg-s3 wireguard_wgs_ts2[10698]: [#] wg setconf wgs_ts2 /dev/fd/63
  

  • Hier sind einige häufige Fehlermeldungen, die Sie bei Fehlkonfiguration Ihrer Tunnel sehen könnten:
    • Fehler: RTNETLINK antwortet: Adresse bereits in Verwendung
      • Problem: Jeder Tunnel muss einen einzigartigen Port zum Lauschen verwenden - Sie haben möglicherweise einen doppelten Port zugewiesen (oder vergessen, ihn auf einen benutzerdefinierten zu setzen)
    • Fehler: Fehler bei der Namensauflösung
      • Problem: Der DNS-Hostname, zu dem der Dienst eine Verbindung herstellen möchte, ist nicht (korrekt) gesetzt oder Ihr Ziel-Host hat allgemeine Probleme bei der DNS-Auflösung.
    • Fehler: Tunnel sind konfiguriert, Dienste laufen, aber die Verbindung ist nicht aktiv.
      • Problem: Der Verbindungsport könnte von einer Firewall blockiert sein.

2. Geht der Verkehr über den Tunnel?

Pingen Sie die entfernte WireGuard-Tunnel-IP - in der Konfiguration ist dies die 'Adresse'.

Wichtig: Definieren Sie die zu verwendende Quell-IP!

# .2 ist die entfernte WG-IP; .1 ist die lokale
ping 10.0.1.2 -I 10.0.1.1

Wenn nicht:

• Stellen Sie sicher, dass der Tunnel wirklich läuft!

• Überprüfen Sie, ob die Schlüssel übereinstimmen => wg show all sollte 'die gleiche' öffentliche Schlüssel auf beiden Seiten anzeigen:

  guy@srv1:~# wg show all
  > Schnittstelle: wgx_tx1
  > öffentlicher Schlüssel: FJgEWygMdiqRcTvij3PiXOtPJNtTENQkv301l2PGhwY=
  > ...
  

  guy@srv2:~# wg show all
  > ...
  > Peer: FJgEWygMdiqRcTvij3PiXOtPJNtTENQkv301l2PGhwY=
  > ...
  

  Um nicht übereinstimmende Schlüssel neu zu generieren, entfernen Sie sie einfach aus dem 'files'-Verzeichnis des Controllers und führen Sie die Rolle erneut auf den Servern aus.

3. Wird der Verkehr über den Tunnel geroutet?

Dies gilt nur für Tunnel, die verwendet werden, um entfernte Subnetze zu verbinden.

Wir testen es mit einem weiteren Ping - diesmal unter Verwendung des lokalen Subnetzes (nicht WG-IP).

# 172.30.1.1 ist das remote 'Subnetz'; 172.20.0.1 ist das lokale
ping 172.30.1.1 -I 172.20.0.1
# Sie können auch einen traceroute ausführen, um mehr Informationen über die getätigte Route zu erhalten:
traceroute 172.30.1.1

Wenn Sie motiviert sind => können Sie einen tcpdump auf dem entfernten Host ausführen, um herauszufinden, ob der Verkehr 'durch den Tunnel' kommt.

# 'wgs_ts2' ist das WireGuard-Tunnel-Interface in diesem Beispiel
guy@srv:~# tcpdump -i wgs_ts2
> tcpdump: Ausführliche Ausgabe unterdrückt, verwenden Sie -v[v]... für vollständige Protokoll-Decodierung
> hören auf wgs_ts2, link-type RAW (Raw IP), Snapshot-Länge 262144 Bytes
> 17:00:07.336550 IP 10.0.1.2 > 10.0.1.1: ICMP Echo-Anforderung, id 38770, seq 1, Länge 64
> 17:00:07.336695 IP 10.0.1.1 > 10.0.1.2: ICMP Echo-Antwort, id 38770, seq 1, Länge 64

Wenn nicht:

• Überprüfen Sie, ob eine Firewall den Verkehr zwischen den Hosts blockiert.

  IPTables/NFTables beispielsweise müssen eingehenden UND weiterleitenden Verkehr zulassen.

• Überprüfen Sie Ihre Routing-Konfiguration auf Fehler und vergleichen Sie diese mit der 'laufenden Konfiguration':

  # einfache Übersicht anzeigen
  ip route show all
  # ALLE Routen anzeigen
  ip route show table all
  # unnötige Broadcast-/lokale Routen entfernen
  ip route show table all | grep -vE '^(broadcast|local)\s'
  

• Die Hosts müssen den Verkehr weiterleiten können!

  Stellen Sie sicher, dass die Einstellung 'wireguard.support.traffic_forwarding' aktiviert ist.

• Sie könnten vergessen haben, das Zielnetzwerk zu den 'AllowedIPs' hinzuzufügen.

  Dies ist notwendig für Stern- und Mesh-Topologien!

4. Immer noch Probleme

Es könnte ein Problem/Bug der Rolle oder ein anderer Ausnahmefall sein => Bitte zögern Sie nicht, ein GitHub-Problem zu eröffnen!

Bitte geben Sie die Ergebnisse der Fehlerbehebung im Problem an.