michaelschiemer/deployment/ansible/playbooks/README-WIREGUARD.md

WireGuard VPN Setup

WireGuard VPN-Server Installation und Konfiguration via Ansible.

Übersicht

Dieses Ansible Setup installiert und konfiguriert einen WireGuard VPN-Server auf dem Production-Server, um sicheren Zugriff auf interne Services zu ermöglichen.

Playbooks

1. setup-wireguard.yml

Installiert und konfiguriert den WireGuard VPN-Server.

Features:

• Installiert WireGuard und Tools
• Generiert Server-Keys (falls nicht vorhanden)
• Konfiguriert WireGuard-Server
• Aktiviert IP Forwarding
• Konfiguriert NAT (Masquerading)
• Öffnet Firewall-Port (51820/udp)
• Startet WireGuard-Service

Verwendung:

cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/setup-wireguard.yml

Variablen:

• wireguard_port: Port für WireGuard (Standard: 51820)
• wireguard_network: VPN-Netzwerk (Standard: 10.8.0.0/24)
• wireguard_server_ip: Server-IP im VPN (Standard: 10.8.0.1)

Beispiel mit Custom-Parametern:

ansible-playbook -i inventory/production.yml playbooks/setup-wireguard.yml \
  -e "wireguard_port=51820" \
  -e "wireguard_network=10.8.0.0/24" \
  -e "wireguard_server_ip=10.8.0.1"

2. add-wireguard-client.yml

Fügt einen neuen Client zum WireGuard-Server hinzu.

Features:

• Generiert Client-Keys
• Fügt Client zur Server-Config hinzu
• Erstellt Client-Konfigurationsdatei
• Generiert QR-Code (falls qrencode installiert)
• Restartet WireGuard-Service

Verwendung:

cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/add-wireguard-client.yml \
  -e "client_name=myclient"

Optionale Parameter:

• client_ip: Spezifische Client-IP (Standard: automatisch berechnet)
• allowed_ips: Erlaubte IP-Ranges (Standard: gesamtes VPN-Netzwerk)

Beispiel mit spezifischer IP:

ansible-playbook -i inventory/production.yml playbooks/add-wireguard-client.yml \
  -e "client_name=myclient" \
  -e "client_ip=10.8.0.2"

Wichtige Sicherheitshinweise

SSH-Zugriff bleibt verfügbar

WICHTIG: Die WireGuard-Konfiguration ändert NICHT die SSH-Zugriffsmöglichkeiten:

• ✅ SSH über die normale Server-IP bleibt vollständig funktionsfähig
• ✅ WireGuard routet standardmäßig nur das VPN-Netzwerk (10.8.0.0/24)
• ✅ Normale Internet-Routen werden nicht geändert
• ✅ Firewall-Regeln für SSH (Port 22) werden NICHT entfernt oder blockiert

Die Client-Konfiguration verwendet standardmäßig AllowedIPs = 10.8.0.0/24, was bedeutet, dass nur Traffic für das VPN-Netzwerk über WireGuard geroutet wird. Alle anderen Verbindungen (inkl. SSH) nutzen weiterhin die normale Internet-Verbindung.

Um SSH komplett über VPN zu routen (nicht empfohlen für die erste Installation):

ansible-playbook ... -e "allowed_ips=0.0.0.0/0"

Verzeichnisstruktur

Nach der Installation:

/etc/wireguard/
├── wg0.conf                    # Server-Konfiguration
├── wg0_private.key             # Server-Private-Key (600)
├── wg0_public.key              # Server-Public-Key (644)
└── clients/                    # Client-Konfigurationen
    ├── client1.conf            # Client 1 Config
    └── client2.conf            # Client 2 Config

Client-Konfiguration verwenden

1. Config-Datei auf Client kopieren

# Von Ansible Control Machine
scp -i ~/.ssh/production \
  deploy@94.16.110.151:/etc/wireguard/clients/myclient.conf \
  ~/myclient.conf

2. WireGuard auf Client installieren

Linux:

sudo apt install wireguard wireguard-tools  # Ubuntu/Debian
# oder
sudo yum install wireguard-tools            # CentOS/RHEL

macOS:

brew install wireguard-tools

Windows: Download von https://www.wireguard.com/install/

3. VPN verbinden

Linux/macOS:

sudo wg-quick up ~/myclient.conf
# oder
sudo wg-quick up myclient

Windows: Importiere die .conf-Datei in die WireGuard-App.

4. Verbindung testen

# Ping zum Server
ping 10.8.0.1

# Status prüfen
sudo wg show

# VPN trennen
sudo wg-quick down myclient

QR-Code für Mobile Client

Falls qrencode installiert ist, wird beim Hinzufügen eines Clients automatisch ein QR-Code angezeigt:

ansible-playbook -i inventory/production.yml playbooks/add-wireguard-client.yml \
  -e "client_name=myphone"

Der QR-Code kann mit der WireGuard Mobile App (iOS/Android) gescannt werden.

Firewall-Konfiguration

Das Playbook öffnet automatisch den WireGuard-Port (51820/udp) in UFW, falls installiert.

Manuelle Firewall-Regeln:

# UFW
sudo ufw allow 51820/udp comment 'WireGuard VPN'

# iptables direkt
sudo iptables -A INPUT -p udp --dport 51820 -j ACCEPT

Troubleshooting

WireGuard startet nicht

# Status prüfen
sudo systemctl status wg-quick@wg0

# Logs anzeigen
sudo journalctl -u wg-quick@wg0 -f

# Manuell starten
sudo wg-quick up wg0

Client kann nicht verbinden

1. Firewall prüfen:

   sudo ufw status
   sudo iptables -L -n | grep 51820
   

2. Server-Logs prüfen:

   sudo journalctl -u wg-quick@wg0 -f
   

3. Server-Status prüfen:

   sudo wg show
   

4. Routing prüfen:

   sudo ip route show
   

IP Forwarding nicht aktiv

# Manuell aktivieren
echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward

# Permanent machen
echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Client entfernen

Um einen Client zu entfernen:

# Auf dem Server
sudo nano /etc/wireguard/wg0.conf
# Entferne den [Peer] Block für den Client

sudo wg-quick down wg0
sudo wg-quick up wg0

# Optional: Client-Config löschen
sudo rm /etc/wireguard/clients/clientname.conf

Server-Public-Key abrufen

# Auf dem Server
cat /etc/wireguard/wg0_public.key
# oder
sudo cat /etc/wireguard/wg0_private.key | wg pubkey

Best Practices

1. Backup der Keys: Speichere Server-Keys sicher:

   sudo tar czf wireguard-backup.tar.gz /etc/wireguard/
   

2. Regelmäßige Updates:

   sudo apt update && sudo apt upgrade wireguard wireguard-tools
   

3. Monitoring: Überwache VPN-Verbindungen:

   sudo wg show
   

4. Sicherheit:

   • Verwalte Client-Keys sicher
   • Entferne nicht genutzte Clients
   • Nutze starke Passwörter für Server-Zugriff

Support

Bei Problemen:

1. Prüfe Logs: sudo journalctl -u wg-quick@wg0
2. Prüfe Status: sudo wg show
3. Prüfe Firewall: sudo ufw status
4. Teste Connectivity: ping 10.8.0.1 (vom Client)