customer-installer/NGINX_PROXY_SETUP.md

# OPNsense NGINX Reverse Proxy Setup

Dieses Script automatisiert die Konfiguration eines NGINX Reverse Proxys auf OPNsense für n8n-Instanzen.

## Voraussetzungen

- OPNsense Firewall mit NGINX Plugin
- API-Zugang zu OPNsense (API Key + Secret)
- Wildcard-Zertifikat für die Domain (z.B. *.userman.de)

## Installation

Das Script befindet sich im Repository unter `setup_nginx_proxy.sh`.

## Verwendung

### Proxy einrichten

```bash
# Minimale Konfiguration
bash setup_nginx_proxy.sh \
  --ctid 768736636 \
  --hostname sb-1768736636 \
  --fqdn sb-1768736636.userman.de \
  --backend-ip 192.168.45.135

# Mit Debug-Ausgabe
bash setup_nginx_proxy.sh --debug \
  --ctid 768736636 \
  --hostname sb-1768736636 \
  --fqdn sb-1768736636.userman.de \
  --backend-ip 192.168.45.135

# Mit benutzerdefiniertem Backend-Port
bash setup_nginx_proxy.sh \
  --ctid 768736636 \
  --hostname sb-1768736636 \
  --fqdn sb-1768736636.userman.de \
  --backend-ip 192.168.45.135 \
  --backend-port 8080
```

### Proxy löschen

```bash
# Proxy für eine CTID löschen
bash delete_nginx_proxy.sh --ctid 768736636

# Mit Debug-Ausgabe
bash delete_nginx_proxy.sh --debug --ctid 768736636

# Dry-Run (zeigt was gelöscht würde, ohne zu löschen)
bash delete_nginx_proxy.sh --dry-run --ctid 768736636

# Mit expliziter FQDN
bash delete_nginx_proxy.sh --ctid 768736636 --fqdn sb-1768736636.userman.de
```

### Hilfsfunktionen

```bash
# API-Verbindung testen
bash setup_nginx_proxy.sh --test-connection --debug

# Verfügbare Zertifikate auflisten
bash setup_nginx_proxy.sh --list-certificates --debug
```

## Parameter

### Erforderliche Parameter (für Proxy-Setup)

| Parameter | Beschreibung | Beispiel |
|-----------|--------------|----------|
| `--ctid <id>` | Container ID (wird als Beschreibung verwendet) | `768736636` |
| `--hostname <name>` | Hostname des Containers | `sb-1768736636` |
| `--fqdn <domain>` | Vollständiger Domainname | `sb-1768736636.userman.de` |
| `--backend-ip <ip>` | IP-Adresse des Backends | `192.168.45.135` |

### Optionale Parameter

| Parameter | Beschreibung | Standard |
|-----------|--------------|----------|
| `--backend-port <port>` | Backend-Port | `5678` |
| `--opnsense-host <ip>` | OPNsense IP oder Hostname | `192.168.45.1` |
| `--opnsense-port <port>` | OPNsense WebUI/API Port | `4444` |
| `--certificate-uuid <uuid>` | UUID des SSL-Zertifikats | Auto-Detect |
| `--debug` | Debug-Modus aktivieren | Aus |
| `--help` | Hilfe anzeigen | - |

### Spezielle Befehle

| Parameter | Beschreibung |
|-----------|--------------|
| `--test-connection` | API-Verbindung testen und beenden |
| `--list-certificates` | Verfügbare Zertifikate auflisten und beenden |

## Ausgabe

### Normalmodus (ohne --debug)

Das Script gibt nur JSON auf stdout aus:

```json
{
  "success": true,
  "ctid": "768736636",
  "fqdn": "sb-1768736636.userman.de",
  "backend": "192.168.45.135:5678",
  "nginx": {
    "upstream_server_uuid": "81f5f15b-978c-4839-b794-5ddb9f1c964e",
    "upstream_uuid": "5fe99a9f-35fb-4141-9b89-238333604a0d",
    "location_uuid": "5c3cc080-385a-4800-964d-ab01f33d45a8",
    "http_server_uuid": "946489aa-7212-41b3-93e2-4972f6a26d4e"
  }
}
```

Bei Fehlern:
```json
{"error": "Fehlerbeschreibung"}
```

### Debug-Modus (mit --debug)

Zusätzlich werden Logs auf stderr ausgegeben:

```
[2026-01-18 17:57:04] INFO: Script Version: 1.0.8
[2026-01-18 17:57:04] INFO: Configuration:
[2026-01-18 17:57:04] INFO:   CTID: 768736636
[2026-01-18 17:57:04] INFO:   Hostname: sb-1768736636
...
```

## Erstellte NGINX-Komponenten

Das Script erstellt folgende Komponenten in OPNsense:

1. **Upstream Server** - Backend-Server mit IP und Port
2. **Upstream** - Load-Balancer-Gruppe (verweist auf Upstream Server)
3. **Location** - URL-Pfad-Konfiguration mit WebSocket-Support
4. **HTTP Server** - Virtueller Host mit HTTPS und Zertifikat

### Verknüpfungskette

```
HTTP Server (sb-1768736636.userman.de:443)
    └── Location (/)
        └── Upstream (768736636)
            └── Upstream Server (192.168.45.135:5678)
```

## Umgebungsvariablen

Das Script kann auch über Umgebungsvariablen konfiguriert werden:

```bash
export OPNSENSE_HOST="192.168.45.1"
export OPNSENSE_PORT="4444"
export OPNSENSE_API_KEY="your-api-key"
export OPNSENSE_API_SECRET="your-api-secret"
export CERTIFICATE_UUID="your-cert-uuid"
export DEBUG="1"

bash setup_nginx_proxy.sh --ctid 768736636 ...
```

## Delete Script Parameter

### Erforderliche Parameter

| Parameter | Beschreibung | Beispiel |
|-----------|--------------|----------|
| `--ctid <id>` | Container ID (zum Finden der Komponenten) | `768736636` |

### Optionale Parameter

| Parameter | Beschreibung | Standard |
|-----------|--------------|----------|
| `--fqdn <domain>` | FQDN zum Finden des HTTP Servers | Auto-Detect |
| `--opnsense-host <ip>` | OPNsense IP oder Hostname | `192.168.45.1` |
| `--opnsense-port <port>` | OPNsense WebUI/API Port | `4444` |
| `--dry-run` | Zeigt was gelöscht würde, ohne zu löschen | Aus |
| `--debug` | Debug-Modus aktivieren | Aus |

### Delete Script Ausgabe

```json
{
  "success": true,
  "dry_run": false,
  "ctid": "768736636",
  "deleted_count": 4,
  "failed_count": 0,
  "components": {
    "http_server": "deleted",
    "location": "deleted",
    "upstream": "deleted",
    "upstream_server": "deleted"
  },
  "reconfigure": "ok"
}
```

### Löschreihenfolge

Das Script löscht die Komponenten in der richtigen Reihenfolge (von außen nach innen):

1. **HTTP Server** - Virtueller Host
2. **Location** - URL-Pfad-Konfiguration
3. **Upstream** - Load-Balancer-Gruppe
4. **Upstream Server** - Backend-Server

## Fehlerbehebung

### API-Verbindungsfehler

```bash
# Verbindung testen
bash setup_nginx_proxy.sh --test-connection --debug
```

### Zertifikat nicht gefunden

```bash
# Verfügbare Zertifikate auflisten
bash setup_nginx_proxy.sh --list-certificates --debug

# Zertifikat manuell angeben
bash setup_nginx_proxy.sh --certificate-uuid "695a8b67b35ae" ...
```

### Berechtigungsfehler (403)

Der API-Benutzer benötigt folgende Berechtigungen in OPNsense:
- `NGINX: Settings`
- `NGINX: Service`
- `System: Trust: Certificates` (optional, für Auto-Detect)

## Versionsverlauf

### setup_nginx_proxy.sh

| Version | Änderungen |
|---------|------------|
| 1.0.8 | HTTP Server Suche nach servername statt description |
| 1.0.7 | Listen-Adressen auf Port 80/443 gesetzt |
| 1.0.6 | Listen-Adressen hinzugefügt |
| 1.0.5 | verify_client und access_log_format hinzugefügt |
| 1.0.4 | Korrektes API-Format (httpserver statt http_server) |
| 1.0.3 | Vereinfachte HTTP Server Konfiguration |
| 1.0.0 | Initiale Version |

### delete_nginx_proxy.sh

| Version | Änderungen |
|---------|------------|
| 1.0.1 | Fix: Arithmetik-Fehler bei Counter-Inkrementierung behoben |
| 1.0.0 | Initiale Version |