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

# 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

# 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

# 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:

{
  "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:

{"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:

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

{
  "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

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

Zertifikat nicht gefunden

# 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