michaelschiemer/docs/deployment/WIREGUARD-SETUP.md

# WireGuard VPN Setup - Complete Guide

**Status**: ✅ Active  
**Last Updated**: 2025-10-31  
**Server**: 94.16.110.151 (michaelschiemer.de)

---

## Übersicht

WireGuard ist ein modernes, schnelles und sicheres VPN-Protokoll, das für den sicheren Zugriff auf interne Services auf dem Production-Server verwendet wird.

**Features:**
- ✅ Schnell und performant
- ✅ Moderne Kryptographie
- ✅ Einfache Konfiguration
- ✅ Native Unterstützung in Linux, macOS, Windows, iOS, Android
- ✅ Automatisierte Installation via Ansible

---

## Server-Informationen

**Server-Endpoint:**
- **Host**: 94.16.110.151
- **Port**: 51820 (UDP)
- **VPN-Netzwerk**: 10.8.0.0/24
- **Server-IP (VPN)**: 10.8.0.1

**Server-Public-Key:**
```
hT3OCWZ6ElX79YdAdexSsZnbWLzRM/5szk+XNEBUaS8=
```

**Wichtige Sicherheitshinweise:**
- ✅ SSH-Zugriff über normale 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

**Aktuelle Sicherheitshärtung:**
- 🔒 **Traefik-Dashboard** ist jetzt nur noch über WireGuard VPN erreichbar (VPN-only + BasicAuth)
- 🔒 **Grafana** ist nur noch über WireGuard VPN erreichbar (VPN-only Middleware)
- ✅ Hauptanwendung (`michaelschiemer.de`) bleibt öffentlich erreichbar (wie gewünscht)
- 🔒 Traefik arbeitet hinter WireGuard für interne Services (Dashboard, Monitoring)

**Zukünftige Sicherheitshärtung (geplant):**
- 🔒 Weitere Backend-Dienste (Prometheus, Portainer) können später nur noch über VPN erreichbar sein
- 🔒 Firewall-Regeln können bei Bedarf weiter angepasst werden

---

## Installation

### Server-Installation (via Ansible)

Die Server-Installation erfolgt automatisch via Ansible:

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

**Was wird installiert:**
- WireGuard und Tools
- Server-Keys (generiert oder vorhandene verwendet)
- Server-Konfiguration
- IP Forwarding aktiviert
- NAT (Masquerading) konfiguriert
- Firewall-Port 51820/udp geöffnet
- WireGuard-Service gestartet

### Client hinzufügen

Um einen neuen Client hinzuzufügen:

```bash
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: 10.8.0.0/24)

**Beispiel mit spezifischer IP:**
```bash
ansible-playbook -i inventory/production.yml playbooks/add-wireguard-client.yml \
  -e "client_name=myclient" \
  -e "client_ip=10.8.0.5"
```

---

## Client-Konfiguration

### 1. Config-Datei abrufen

Die Client-Konfigurationsdatei liegt auf dem Server unter:
```
/etc/wireguard/clients/{client_name}.conf
```

**Abrufen der Config-Datei:**

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

Oder direkt auf dem Server:

```bash
ssh -i ~/.ssh/production deploy@94.16.110.151
sudo cat /etc/wireguard/clients/development.conf
```

### 2. WireGuard auf Client installieren

**Linux (Ubuntu/Debian):**
```bash
sudo apt update
sudo apt install wireguard wireguard-tools
```

**Linux (CentOS/RHEL):**
```bash
sudo yum install wireguard-tools
# oder
sudo dnf install wireguard-tools
```

**macOS:**
```bash
brew install wireguard-tools
```

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

**iOS/Android:**
WireGuard App aus dem App Store/Play Store installieren

### 3. VPN verbinden

**Linux/macOS (Command Line):**
```bash
# Config-Datei kopieren
sudo cp ~/development.conf /etc/wireguard/development.conf

# VPN starten
sudo wg-quick up development

# Status prüfen
sudo wg show

# VPN trennen
sudo wg-quick down development
```

**Linux/macOS (Alternative):**
```bash
# Direkt mit Datei
sudo wg-quick up ~/development.conf
```

**Windows:**
1. WireGuard-App öffnen
2. "Import tunnel(s) from file" wählen
3. `development.conf` Datei auswählen
4. "Activate" klicken

**iOS/Android:**
1. WireGuard-App öffnen
2. QR-Code scannen (falls verfügbar) oder Config-Datei importieren
3. Tunnel aktivieren

### 4. QR-Code generieren

Falls `qrencode` auf dem Server installiert ist, kann ein QR-Code generiert werden:

```bash
# Auf dem Server
qrencode -t ansiutf8 < /etc/wireguard/clients/development.conf
# oder für PNG
qrencode -t png -o /tmp/development-qr.png < /etc/wireguard/clients/development.conf
```

---

## Verbindung testen

Nach dem Verbinden mit dem VPN:

### 1. VPN-Status prüfen

```bash
# Status anzeigen
sudo wg show

# Erwartete Ausgabe:
# interface: development
#   public key: <client_public_key>
#   private key: (hidden)
#   listening port: <random_port>
# 
# peer: hT3OCWZ6ElX79YdAdexSsZnbWLzRM/5szk+XNEBUaS8=
#   endpoint: 94.16.110.151:51820
#   allowed ips: 10.8.0.0/24
#   latest handshake: <timestamp>
#   transfer: <received>, <sent>
```

### 2. Server-IP pingen

```bash
# Server im VPN-Netzwerk pingen
ping 10.8.0.1

# Sollte erfolgreich sein
```

### 3. VPN-Netzwerk prüfen

```bash
# Routing-Tabelle prüfen
ip route show

# Sollte einen Eintrag für 10.8.0.0/24 über wg0 zeigen
```

### 4. Services über VPN erreichen

Nach erfolgreicher VPN-Verbindung sollten folgende Services über das VPN-Netzwerk erreichbar sein:

- **Prometheus**: http://10.8.0.1:9090
- **Grafana**: http://10.8.0.1:3000
- **Portainer**: https://10.8.0.1:9443

**Hinweis**: 
- ⚠️ Aktuell sind diese Services auch öffentlich erreichbar (Traefik-Routing)
- 🔒 **Geplant**: Später sollen alle Backend-Dienste nur noch über VPN erreichbar sein
- ✅ Für die Einrichtung bleibt der öffentliche Zugriff vorerst aktiviert

---

## Client-Verwaltung

### Client-Liste anzeigen

```bash
# Auf dem Server
sudo wg show

# Zeigt alle verbundenen Clients
```

### Client-Config-Dateien anzeigen

```bash
# Auf dem Server
ls -la /etc/wireguard/clients/
```

### Client entfernen

Um einen Client zu entfernen:

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

# WireGuard neu starten
sudo wg-quick down wg0
sudo wg-quick up wg0

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

Oder über Ansible (manuelle Datei-Bearbeitung erforderlich):

```bash
# 1. Client aus /etc/wireguard/wg0.conf entfernen
# 2. WireGuard-Service neu starten:
cd deployment/ansible
ansible production -m shell -a "sudo wg-quick down wg0 && sudo wg-quick up wg0"
```

---

## Troubleshooting

### VPN verbindet nicht

**1. Firewall prüfen:**
```bash
# Auf dem Server
sudo ufw status | grep 51820
# Sollte zeigen: 51820/udp ALLOW

# Falls nicht:
sudo ufw allow 51820/udp comment 'WireGuard VPN'
```

**2. WireGuard-Service prüfen:**
```bash
# Auf dem Server
sudo systemctl status wg-quick@wg0

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

**3. Server-Konfiguration prüfen:**
```bash
# Auf dem Server
sudo wg show
sudo cat /etc/wireguard/wg0.conf
```

**4. Client-Config prüfen:**
- Endpoint korrekt? (94.16.110.151:51820)
- Server-Public-Key korrekt?
- Client-Private-Key vorhanden?
- AllowedIPs korrekt?

**5. Netzwerk-Verbindung prüfen:**
```bash
# Vom Client aus
ping 94.16.110.151
# Sollte erfolgreich sein

# UDP-Port testen
nc -u -v 94.16.110.151 51820
```

### VPN verbindet, aber kein Traffic

**1. IP Forwarding prüfen:**
```bash
# Auf dem Server
cat /proc/sys/net/ipv4/ip_forward
# Sollte "1" sein

# Falls nicht:
echo 1 | sudo tee /proc/sys/net/ipv4/ip_forward
echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

**2. NAT-Rules prüfen:**
```bash
# Auf dem Server
sudo iptables -t nat -L -n | grep MASQUERADE
sudo iptables -L FORWARD -n | grep wg0
```

**3. Routing prüfen:**
```bash
# Auf dem Server
ip route show
# Sollte Routes für wg0 zeigen

# Vom Client
ip route show
# Sollte Route für 10.8.0.0/24 über VPN zeigen
```

### SSH-Zugriff funktioniert nicht mehr

**WICHTIG**: SSH-Zugriff sollte weiterhin über die normale IP funktionieren!

```bash
# SSH über normale IP (nicht VPN)
ssh -i ~/.ssh/production deploy@94.16.110.151

# Falls nicht funktioniert:
# 1. Prüfe, ob VPN alle Traffic routet (AllowedIPs = 0.0.0.0/0)
# 2. Deaktiviere VPN: sudo wg-quick down development
# 3. Prüfe Firewall: sudo ufw status | grep 22
```

### Performance-Probleme

**1. MTU anpassen:**
```bash
# In Client-Config hinzufügen:
# [Interface]
# MTU = 1420
```

**2. PersistKeepalive anpassen:**
```bash
# In Client-Config bereits konfiguriert:
# PersistentKeepalive = 25
```

**3. Server-Last prüfen:**
```bash
# Auf dem Server
sudo wg show
# Zeigt Transfer-Statistiken
```

---

## Best Practices

### Sicherheit

1. **Backup der Server-Keys:**
   ```bash
   # Auf dem Server
   sudo tar czf wireguard-backup.tar.gz /etc/wireguard/
   # Sicher speichern (z.B. verschlüsselt)
   ```

2. **Client-Keys sicher verwalten:**
   - Client-Private-Keys niemals teilen
   - Config-Dateien sicher speichern
   - Nicht genutzte Clients entfernen

3. **Regelmäßige Updates:**
   ```bash
   # Auf dem Server
   sudo apt update && sudo apt upgrade wireguard wireguard-tools
   ```

4. **Firewall-Regeln:**
   - Nur notwendige Ports öffnen
   - Regelmäßig Firewall-Status prüfen

### Monitoring

1. **VPN-Verbindungen überwachen:**
   ```bash
   # Auf dem Server
   sudo wg show
   ```

2. **Logs prüfen:**
   ```bash
   # Auf dem Server
   sudo journalctl -u wg-quick@wg0 -f
   ```

3. **Transfer-Statistiken:**
   ```bash
   # Auf dem Server
   sudo wg show
   # Zeigt received/sent für jeden Client
   ```

---

## Ansible Playbooks

### Setup WireGuard Server

**Datei**: `deployment/ansible/playbooks/setup-wireguard.yml`

**Verwendung:**
```bash
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)

### Add WireGuard Client

**Datei**: `deployment/ansible/playbooks/add-wireguard-client.yml`

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

**Variablen:**
- `client_name`: Name des Clients (erforderlich)
- `client_ip`: Spezifische Client-IP (Standard: automatisch berechnet)
- `allowed_ips`: Erlaubte IP-Ranges (Standard: 10.8.0.0/24)
- `wireguard_dns_servers`: Liste interner Resolver (Default: WireGuard-Server-IP, z.B. `["10.8.0.1"]`)

**Dokumentation**: Siehe `deployment/ansible/playbooks/README-WIREGUARD.md`

> Nach dem Lauf liegt die Client-Konfiguration zusätzlich lokal im Repository unter  
> `deployment/ansible/wireguard-clients/<client_name>.conf` – ideal zum direkten
> Import auf deinem Admin-Rechner (Datei bleibt mit `chmod 600` geschützt).

### Interner DNS (CoreDNS) für VPN-Clients

**Datei**: `deployment/ansible/playbooks/setup-infrastructure.yml` (Tag `dns`)

**Verwendung:**
```bash
cd deployment/ansible
ANSIBLE_VAULT_PASSWORD_FILE=secrets/.vault_pass \
ansible-playbook -i inventory/production.yml playbooks/setup-infrastructure.yml --tags dns
```

**Konfiguration:**
- DNS-Records definieren sich über `dns_records` (Default in `group_vars/production.yml` → `grafana.<app_domain>` → `10.8.0.1`)
- Zusätzliche Einträge können per Override vor dem Playbook-Lauf gesetzt werden, z.B.:
  ```bash
  ansible-playbook ... --tags dns \
    -e 'dns_records=[{"host":"grafana.michaelschiemer.de","address":"10.8.0.1"},{"host":"prometheus.michaelschiemer.de","address":"10.8.0.1"}]'
  ```
- Upstream-Resolver werden über `dns_forwarders` gesteuert (Standard: `1.1.1.1`, `8.8.8.8`)

**Ergebnis:**
- CoreDNS läuft auf dem Server via `network_mode: host` (UDP/TCP 53)
- Alle VPN-Clients können `grafana.michaelschiemer.de` (und weitere Overrides) direkt auf `10.8.0.1` auflösen
- Nicht hinterlegte Hostnamen werden dank `fallthrough` automatisch an die definierten Upstream-Resolver weitergereicht
- Traefik-Middleware `grafana-vpn-only` akzeptiert ausschließlich Verbindungen aus dem WireGuard-Netz `10.8.0.0/24`
- HTTP-Aufrufe zu Grafana laufen so automatisch durch den WireGuard-Tunnel

---

## Verzeichnisstruktur

**Auf dem Server:**

```
/etc/wireguard/
├── wg0.conf                    # Server-Konfiguration
├── wg0_private.key             # Server-Private-Key (600)
├── wg0_public.key             # Server-Public-Key (644)
└── clients/                    # Client-Konfigurationen
    ├── development.conf        # Development-Client
    └── ...
```

**Auf dem Client (Linux/macOS):**

```
/etc/wireguard/
└── development.conf            # Client-Konfiguration (600)
```

---

## Support

Bei Problemen:

1. **Logs prüfen:**
   ```bash
   sudo journalctl -u wg-quick@wg0 -f
   ```

2. **Status prüfen:**
   ```bash
   sudo wg show
   ```

3. **Firewall prüfen:**
   ```bash
   sudo ufw status
   ```

4. **Connectivity testen:**
   ```bash
   ping 10.8.0.1  # Vom Client
   ```

5. **Ansible Playbook erneut ausführen:**
   ```bash
   cd deployment/ansible
   ansible-playbook -i inventory/production.yml playbooks/setup-wireguard.yml
   ```

---

## Referenzen

- **WireGuard-Website**: https://www.wireguard.com/
- **WireGuard-Installation**: https://www.wireguard.com/install/
- **WireGuard-Dokumentation**: https://www.wireguard.com/papers/wireguard.pdf
- **Ansible Playbook-Dokumentation**: `deployment/ansible/playbooks/README-WIREGUARD.md`

---

**Zuletzt aktualisiert**: 2025-10-31  
**Version**: 1.0