From fbf62e6e48f7b942ef074ba62eb8a90d40f094e4 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 28 Jun 2026 11:14:24 +0200 Subject: [PATCH] Doku: allgemeines OPNsense-Docker-Routing-How-To in shared. VM-101-Instanz verweist auf shared; Duplikate reduziert. Co-authored-by: Cursor --- README.md | 4 +- guests/README.md | 1 + guests/vm101-ubuntu/README.md | 2 +- .../vm101-ubuntu/docbr0-opnsense-routing.md | 165 ++++---------- pve1/00_README.md | 3 +- shared/infrastruktur-netzwerk.md | 2 +- shared/opnsense-docker-subnet-routing.md | 210 ++++++++++++++++++ 7 files changed, 258 insertions(+), 129 deletions(-) create mode 100644 shared/opnsense-docker-subnet-routing.md diff --git a/README.md b/README.md index 57990c1..d169bfc 100644 --- a/README.md +++ b/README.md @@ -30,11 +30,13 @@ docu/ | Datei | Inhalt | |-------|--------| | [shared/infrastruktur-netzwerk.md](shared/infrastruktur-netzwerk.md) | VLANs, IPs, Bridges | +| [shared/opnsense-docker-subnet-routing.md](shared/opnsense-docker-subnet-routing.md) | How-To: Docker-Subnetz über OPNsense erreichbar machen | | [shared/mqtt-homeassistant.md](shared/mqtt-homeassistant.md) | MQTT-Broker, HA Discovery, Credentials | | [shared/git-und-repos.md](shared/git-und-repos.md) | Gitea, Tokens, Clone-Pfade | | [migration/nextcloud-optimierung-und-updates.md](migration/nextcloud-optimierung-und-updates.md) | Nextcloud VM 101: Updates, Tuning, notify_push | | [guests/](guests/) | Docker-Stacks pro Gast (Compose, ohne Volumes/Daten) | -| [guests/vm101-ubuntu/docbr0-opnsense-routing.md](guests/vm101-ubuntu/docbr0-opnsense-routing.md) | OPNsense: 10.2.2.0/24 erreichbar machen | +| [guests/vm101-ubuntu/docbr0-opnsense-routing.md](guests/vm101-ubuntu/docbr0-opnsense-routing.md) | VM 101: docbr0 Instanz | +| [shared/opnsense-docker-subnet-routing.md](shared/opnsense-docker-subnet-routing.md) | How-To: Docker-Subnetz über OPNsense | ## Code-Repos (separat von dieser Doku) diff --git a/guests/README.md b/guests/README.md index 90d590b..17e45c2 100644 --- a/guests/README.md +++ b/guests/README.md @@ -12,6 +12,7 @@ Passwörter in den Repo-Dateien sind durch `REDACTED` ersetzt. Live-Werte nur au | Gast | Routing / OPNsense | |------|-------------------| +| *(allgemein)* | [../shared/opnsense-docker-subnet-routing.md](../shared/opnsense-docker-subnet-routing.md) | | [vm101-ubuntu](vm101-ubuntu/) | [docbr0-opnsense-routing.md](vm101-ubuntu/docbr0-opnsense-routing.md) | **Sync vom Gast (Beispiel VM 101):** diff --git a/guests/vm101-ubuntu/README.md b/guests/vm101-ubuntu/README.md index d3ab435..a857f93 100644 --- a/guests/vm101-ubuntu/README.md +++ b/guests/vm101-ubuntu/README.md @@ -12,7 +12,7 @@ Externes Docker-Netz für Container mit **festen IPs** (`10.2.2.0/24`). -**Erreichbarkeit aus LAN/VLANs:** [docbr0-opnsense-routing.md](docbr0-opnsense-routing.md) +**Erreichbarkeit aus LAN/VLANs:** [docbr0-opnsense-routing.md](docbr0-opnsense-routing.md) (Instanz) · [How-To](../../shared/opnsense-docker-subnet-routing.md) (allgemein) | Stack / Service | Container | IP (docbr0) | |-----------------|-----------|-------------| diff --git a/guests/vm101-ubuntu/docbr0-opnsense-routing.md b/guests/vm101-ubuntu/docbr0-opnsense-routing.md index d876f7a..62d1100 100644 --- a/guests/vm101-ubuntu/docbr0-opnsense-routing.md +++ b/guests/vm101-ubuntu/docbr0-opnsense-routing.md @@ -1,126 +1,64 @@ # docbr0 (10.2.2.0/24) — Routing & OPNsense -**Zweck:** Container mit festen IPs auf VM 101 aus dem lokalen Netz (LAN/VLANs) erreichbar machen. -**Stand:** 2026-06-28 -**Betrifft:** OPNsense · VM 101 `ubuntu` (192.168.10.10) · Docker-Netz `docbr0` +**Instanz:** VM 101 `ubuntu` auf pve1 +**Allgemeine Anleitung:** [../../shared/opnsense-docker-subnet-routing.md](../../shared/opnsense-docker-subnet-routing.md) --- -## Kurzfassung +## Werte für diese Instanz -| Was | Wo | -|-----|-----| -| Docker-Netz | `10.2.2.0/24` (`docbr0`, extern) | -| Gateway für Container | **10.2.2.1** = VM 101 (Docker-Bridge auf dem Host) | -| VM Management-IP | **192.168.10.10** (VLAN 10 / 192.168.10.0/24) | -| OPNsense | Statische Route **10.2.2.0/24 → 192.168.10.10** + Firewall Pass | +| Variable | Wert | +|----------|------| +| `DOCKER_SUBNET` | `10.2.2.0/24` | +| `DOCKER_HOST` | `192.168.10.10` | +| Docker-Netzname | `docbr0` (extern) | +| Bridge-Gateway (Host) | `10.2.2.1` | +| OPNsense Gateway-Name | `VM101_DOCKER` | +| Firewall-Alias | `DOCKER_DOCBR0` | -`10.2.2.1` ist **kein OPNsense-Interface** — nur die Bridge auf der VM. +`10.2.2.1` ist **kein OPNsense-Interface** — nur die Docker-Bridge auf VM 101. --- ## Topologie ``` -Client (z.B. 192.168.10.50 oder 192.168.40.x) - │ +Client (192.168.10.x / andere VLANs) ▼ OPNsense (192.168.10.1) - │ Route: 10.2.2.0/24 via 192.168.10.10 - │ Firewall: Pass (Quell-VLAN → 10.2.2.0/24) + │ Route: 10.2.2.0/24 → 192.168.10.10 ▼ - VM 101 (192.168.10.10 eth0 + 10.2.2.1 docbr0) - │ ip_forward=1, FORWARD ACCEPT + VM 101 (192.168.10.10 + 10.2.2.1 docbr0) ▼ - Docker-Container (10.2.2.x) + Container (10.2.2.x) ├── 10.2.2.254 NPM ├── 10.2.2.253 Nextcloud - ├── 10.2.2.22 Gitea (git2) └── … siehe [README.md](README.md) ``` -**Rückweg:** Container → Gateway 10.2.2.1 → VM → eth0 → OPNsense → Client. -Kein NAT nötig (intern → intern). +--- + +## OPNsense (Kurz) + +Siehe [How-To](../../shared/opnsense-docker-subnet-routing.md) für Screenshots-Felder im Detail. + +1. Gateway **VM101_DOCKER** → `192.168.10.10` auf LAN/VLAN10 +2. Route **10.2.2.0/24** via VM101_DOCKER +3. Firewall Pass: Quell-VLAN → `10.2.2.0/24` (pro Interface) +4. Apply Changes --- -## OPNsense einrichten - -### 1. Gateway (falls noch nicht vorhanden) - -**System → Gateways → Configuration → Single → +** - -| Feld | Wert | -|------|------| -| Name | `VM101_DOCKER` | -| Interface | LAN / VLAN10 (`192.168.10.0/24`) | -| IP address | **192.168.10.10** | -| Disable Gateway Monitoring | optional an (Host pingt evtl. nicht als GW) | -| Description | Docker docbr0 VM 101 | - -### 2. Statische Route - -**System → Routes → Configuration → +** - -| Feld | Wert | -|------|------| -| Network | **10.2.2.0/24** | -| Gateway | **VM101_DOCKER** (192.168.10.10) | -| Description | Docker docbr0 VM101 | - -**Apply Changes.** - -### 3. Firewall-Regeln - -**Firewall → Aliases → +** (optional, übersichtlicher) - -| Name | Type | Content | -|------|------|---------| -| `DOCKER_DOCBR0` | Network | `10.2.2.0/24` | - -**Firewall → Rules →** Interface der **Quelle** (z.B. **LAN** für 192.168.10.0/24): - -| Feld | Wert | -|------|------| -| Action | Pass | -| Interface | LAN (bzw. VLAN10) | -| Protocol | any | -| Source | LAN net (oder spezifisches VLAN) | -| Destination | `DOCKER_DOCBR0` / `10.2.2.0/24` | -| Description | Allow → Docker docbr0 VM101 | - -**Weitere VLANs:** dieselbe Logik auf **jedem** Interface, von dem aus Clients kommen (z.B. IoT `192.168.40.0/24`), sonst blockiert Inter-VLAN-Firewall. - -Regel **oben** platzieren (vor generischen Block-Regeln). - -**Apply Changes.** - ---- - -## Was bewusst nicht auf OPNsense - -| Maßnahme | Grund | -|----------|--------| -| Interface/VLAN `10.2.2.0/24` auf OPNsense | Netz existiert nur auf VM 101 | -| Outbound NAT intern → 10.2.2.x | Routing reicht | -| Port-Forward von WAN auf 10.2.2.x | Normaler Weg: DNS → NPM (10.2.2.254) | - ---- - -## VM 101 (Docker-Host) - -Bereits vorhanden / relevant: +## VM 101 — Host-Checks | Check | Erwartung | |-------|-----------| -| Bridge | `10.2.2.1/24` auf `docbr0` / `br-0362a13fe302` | +| Bridge | `10.2.2.1/24` auf `docbr0` | | `ip_forward` | `1` | -| FORWARD | policy ACCEPT | -| Docker | `"iptables": false` — Fest-IPs auf docbr0 bleiben stabil | -| Container-Internet | manuelles NAT → [../../pve1/scripts/vm101-docker-nat-rules.sh](../../pve1/scripts/vm101-docker-nat-rules.sh) | +| Docker | `"iptables": false` | +| Container-Internet | [vm101-docker-nat-rules.sh](../../pve1/scripts/vm101-docker-nat-rules.sh) | ```bash -# Auf VM 101 ip route | grep 10.2.2 ping -c1 10.2.2.253 ping -c1 10.2.2.254 @@ -129,44 +67,22 @@ sudo docker network inspect docbr0 --format '{{range .IPAM.Config}}{{.Subnet}}{{ --- -## Tests - -### Vom Client (lokal / VLAN) +## Tests (diese Instanz) ```bash -traceroute 10.2.2.253 # erwartet Hop über 192.168.10.10 -ping 10.2.2.254 +traceroute 10.2.2.253 curl -sI http://10.2.2.253/status.php curl -sI http://10.2.2.254 ``` -### Von OPNsense (Diagnostics → Ping) - -- Ziel `192.168.10.10` → OK -- Ziel `10.2.2.253` → OK (wenn Route + VM-Forward stimmen) - --- -## Fehlerbilder +## Alltag vs. Admin -| Symptom | Wahrscheinliche Ursache | -|---------|-------------------------| -| Timeout, kein Hop zu .10 | Statische Route fehlt oder falscher Gateway | -| Hop zu .10, dann Timeout | VM: Forwarding / Bridge; Container down | -| Ping OK, HTTP nein | Container-Port / Dienst; nicht OPNsense | -| Nur aus einem VLAN | Firewall-Regel fehlt auf Quell-Interface | -| WAN-Zugriff gewünscht | Separat: DNS + NPM, nicht direkte 10.2.2-Route | - ---- - -## Alltag vs. Admin-Zugriff - -| Zugriff | Empfehlung | -|---------|------------| -| **Benutzer** | Hostname (`cloud.jeanavril.com`) → NPM (10.2.2.254) → Backend | -| **Admin / Debug** | Direkt `10.2.2.x` nach Route (Dockge, Container-Logs, Bypass NPM) | - -Split-DNS oder lokaler DNS-Eintrag für interne Namen ist unabhängig von der statischen Route — beides kann parallel existieren. +| Zugriff | Weg | +|---------|-----| +| Benutzer | Hostname → NPM (`10.2.2.254`) → Backend | +| Admin | Direkt `10.2.2.x` (Dockge, Logs, Bypass NPM) | --- @@ -174,7 +90,6 @@ Split-DNS oder lokaler DNS-Eintrag für interne Namen ist unabhängig von der st | Dokument | Inhalt | |----------|--------| -| [README.md](README.md) | Stack-Liste, docbr0-IP-Tabelle | -| [../../pve1/06_ubuntu-vm-nextcloud.md](../../pve1/06_ubuntu-vm-nextcloud.md) | Nextcloud, NPM, notify_push | -| [../../shared/infrastruktur-netzwerk.md](../../shared/infrastruktur-netzwerk.md) | VLANs, Proxmox-Hosts | -| [../../pve1/scripts/vm101-docker-nat-rules.sh](../../pve1/scripts/vm101-docker-nat-rules.sh) | Container-Internet (NAT) | +| [README.md](README.md) | Stack-Liste, IP-Tabelle | +| [../../pve1/06_ubuntu-vm-nextcloud.md](../../pve1/06_ubuntu-vm-nextcloud.md) | Nextcloud, notify_push | +| [../../shared/opnsense-docker-subnet-routing.md](../../shared/opnsense-docker-subnet-routing.md) | Allgemeines How-To | diff --git a/pve1/00_README.md b/pve1/00_README.md index 04237c4..303c02e 100644 --- a/pve1/00_README.md +++ b/pve1/00_README.md @@ -17,7 +17,8 @@ | 06 | [06_ubuntu-vm-nextcloud.md](06_ubuntu-vm-nextcloud.md) | VM 101 ubuntu, Nextcloud Status & Optimierung | | — | [scripts/](scripts/) | VM-101-Skripte (NAT, Wartungs-Cron, crontab) | | — | [../guests/vm101-ubuntu/](../guests/vm101-ubuntu/) | VM 101 Docker-Stacks (Compose, ohne Daten) | -| — | [../guests/vm101-ubuntu/docbr0-opnsense-routing.md](../guests/vm101-ubuntu/docbr0-opnsense-routing.md) | OPNsense: Route/Firewall für 10.2.2.0/24 | +| — | [../shared/opnsense-docker-subnet-routing.md](../shared/opnsense-docker-subnet-routing.md) | How-To: Docker-Subnetz über OPNsense | +| — | [../guests/vm101-ubuntu/docbr0-opnsense-routing.md](../guests/vm101-ubuntu/docbr0-opnsense-routing.md) | VM 101 docbr0 (Instanz) | ## Shared diff --git a/shared/infrastruktur-netzwerk.md b/shared/infrastruktur-netzwerk.md index ec5b702..085507c 100644 --- a/shared/infrastruktur-netzwerk.md +++ b/shared/infrastruktur-netzwerk.md @@ -34,7 +34,7 @@ Schema: VLAN-ID oft = drittes Oktett (`192.168.40.0/24` = VLAN 40) Details CT/VM-Netze: siehe Host-Doku unter `pve1/` bzw. `pve2/`. -**Docker docbr0 auf VM 101 (10.2.2.0/24):** OPNsense-Route + Firewall → [guests/vm101-ubuntu/docbr0-opnsense-routing.md](../guests/vm101-ubuntu/docbr0-opnsense-routing.md) +**Docker-Subnetze hinter einem Host:** allgemeines How-To → [opnsense-docker-subnet-routing.md](opnsense-docker-subnet-routing.md) · Instanz VM 101 → [guests/vm101-ubuntu/docbr0-opnsense-routing.md](../guests/vm101-ubuntu/docbr0-opnsense-routing.md) ## Rollen diff --git a/shared/opnsense-docker-subnet-routing.md b/shared/opnsense-docker-subnet-routing.md new file mode 100644 index 0000000..1fb450e --- /dev/null +++ b/shared/opnsense-docker-subnet-routing.md @@ -0,0 +1,210 @@ +# How-To: Docker-Subnetz über OPNsense erreichbar machen + +**Zweck:** Generelle Anleitung, wenn Docker-Container auf einem **eigenen Subnetz** hängen (z. B. externes Netz `docbr0` mit festen IPs) und Clients aus LAN/VLANs diese IPs erreichen sollen. + +**Stand:** 2026-06-28 + +--- + +## Wann braucht man das? + +Typisches Setup: + +| Ebene | Beispiel | +|-------|----------| +| Client | `192.168.10.50` oder `192.168.40.x` | +| OPNsense | Gateway `.1`, routet zwischen VLANs | +| Docker-Host (VM/CT) | Management-IP z. B. `192.168.10.10` | +| Docker-Bridge (extern) | eigenes Subnetz z. B. `10.2.2.0/24` | +| Container | feste IP z. B. `10.2.2.254` (NPM) | + +Das Docker-Subnetz ist **nur auf dem Host** — OPNsense hat kein Interface dort. OPNsense muss Pakete an die **Management-IP des Hosts** weiterleiten; der Host leitet auf die Bridge weiter. + +``` +Client → OPNsense → Docker-Host (Mgmt-IP) → Docker-Bridge → Container +``` + +**Nicht verwechseln:** Die `.1` im Docker-Subnetz ist meist der **Host** (Bridge-Gateway), nicht OPNsense. + +--- + +## Voraussetzungen auf dem Docker-Host + +Vor der OPNsense-Konfiguration prüfen: + +| Check | Befehl / Erwartung | +|-------|-------------------| +| Bridge existiert | `ip -br addr` zeigt Subnetz (z. B. `10.2.2.1/24`) | +| Container erreichbar (lokal) | `ping 10.2.2.x` vom Host | +| IP-Forwarding | `sysctl net.ipv4.ip_forward` → `1` | +| Forwarding erlaubt | `iptables -L FORWARD` — policy ACCEPT oder explizite Regeln | + +### Docker mit `"iptables": false` + +Wenn Docker **keine** iptables-Regeln setzt (häufig bei festen Container-IPs): + +- **Routing LAN → Container:** meist ohne extra NAT auf dem Host +- **Container → Internet:** separates manuelles MASQUERADE nötig (eigenes Thema, siehe [pve1/scripts/vm101-docker-nat-rules.sh](../pve1/scripts/vm101-docker-nat-rules.sh)) + +Compose-Beispiel externes Netz: + +```yaml +networks: + docbr0: + external: true + +services: + app: + networks: + docbr0: + ipv4_address: 10.2.2.254 +``` + +Netz vorher anlegen: `docker network create --subnet=10.2.2.0/24 docbr0` + +--- + +## OPNsense — Schritt für Schritt + +Variablen für **jeden** neuen Fall anpassen: + +| Variable | Bedeutung | Beispiel VM 101 | +|----------|-----------|-----------------| +| `DOCKER_SUBNET` | Container-Netz | `10.2.2.0/24` | +| `DOCKER_HOST` | Management-IP des Hosts | `192.168.10.10` | +| `HOST_IF` | OPNsense-Interface zum Host | LAN / VLAN10 | +| `GW_NAME` | Name des Gateways in OPNsense | `VM101_DOCKER` | + +### 1. Gateway anlegen + +**System → Gateways → Configuration → Single → +** + +| Feld | Wert | +|------|------| +| Name | `GW_NAME` | +| Interface | Interface, auf dem `DOCKER_HOST` erreichbar ist | +| IP address | `DOCKER_HOST` | +| Disable Gateway Monitoring | optional an (Host antwortet evtl. nicht als Router-GW) | +| Description | kurz: welcher Docker-Host / welches Netz | + +### 2. Statische Route + +**System → Routes → Configuration → +** + +| Feld | Wert | +|------|------| +| Network | `DOCKER_SUBNET` | +| Gateway | eben angelegtes Gateway (`DOCKER_HOST`) | +| Description | z. B. `Docker subnet via VM101` | + +**Save → Apply Changes.** + +Damit gilt für alle Clients mit OPNsense als Default-GW: *Traffic nach `DOCKER_SUBNET` → an `DOCKER_HOST`.* + +### 3. Firewall — Alias (empfohlen) + +**Firewall → Aliases → +** + +| Name | Type | Content | +|------|------|---------| +| z. B. `DOCKER_SUBNET_VM101` | Network | `10.2.2.0/24` | + +### 4. Firewall — Pass-Regel + +**Firewall → Rules →** Interface der **Quell-Netze** (z. B. LAN, IoT, …): + +| Feld | Wert | +|------|------| +| Action | Pass | +| Interface | Quell-VLAN (z. B. LAN) | +| Protocol | any | +| Source | Quellnetz (z. B. LAN net) | +| Destination | Alias / `DOCKER_SUBNET` | +| Description | Allow → Docker subnet via … | + +**Wichtig:** Pro **Quell-Interface** eine Regel — wer aus VLAN 40 kommt, braucht eine Regel auf dem IoT-Interface, nicht nur auf LAN. + +Regeln **oben** (vor Block-Regeln). **Apply Changes.** + +### 5. Was auf OPNsense weglassen + +| Maßnahme | Grund | +|----------|--------| +| Neues Interface/VLAN für Docker-Subnetz | Netz lebt nur auf dem Docker-Host | +| Outbound NAT Quelle → Docker-Subnetz | internes Routing reicht | +| Port-Forward WAN → Container-IP | üblich: Reverse Proxy + DNS | + +--- + +## Tests + +### 1. OPNsense → Docker-Host + +**Diagnostics → Ping:** `DOCKER_HOST` → OK + +### 2. OPNsense → Container (optional) + +Ping `10.2.2.x` — funktioniert nur, wenn der Host ICMP weiterleitet und Container antwortet. + +### 3. Client im LAN/VLAN + +```bash +traceroute 10.2.2.254 # Hop über DOCKER_HOST erwartet +ping 10.2.2.254 +curl -sI http://10.2.2.254 # falls HTTP-Dienst +``` + +### 4. Docker-Host lokal + +```bash +ip route | grep 10.2.2 +ping -c1 10.2.2.254 +docker ps --filter network=docbr0 +``` + +--- + +## Fehlerbilder + +| Symptom | Ursache | Maßnahme | +|---------|---------|----------| +| Timeout, kein Hop zum Host | Route fehlt / falscher GW | Route + Gateway prüfen | +| Hop zum Host, dann Timeout | Host: Forwarding, Bridge, Container down | `ip_forward`, `ping` vom Host | +| Nur aus einem VLAN erreichbar | Firewall nur auf einem Interface | Regel auf Quell-VLAN | +| Ping OK, Dienst nein | Port / Container / App-Firewall | Dienst auf Container prüfen | +| Route da, plötzlich weg | CARP/Failover, Config nicht sync | Backup-OPNsense Routes vergleichen | + +--- + +## Checkliste (Copy-Paste für neue Instanz) + +``` +[ ] DOCKER_SUBNET und DOCKER_HOST notiert +[ ] Host: Bridge + ip_forward + lokaler ping 10.2.2.x +[ ] OPNsense: Gateway → DOCKER_HOST +[ ] OPNsense: Route DOCKER_SUBNET via Gateway +[ ] OPNsense: Firewall Pass pro Quell-VLAN +[ ] Apply Changes +[ ] Test: traceroute vom Client +[ ] Doku: guests//… oder Host-README verlinken +``` + +--- + +## Instanzen in dieser Umgebung + +| Gast | Docker-Subnetz | Host (Mgmt) | Detail-Doku | +|------|----------------|-------------|-------------| +| VM 101 ubuntu (pve1) | `10.2.2.0/24` (`docbr0`) | `192.168.10.10` | [guests/vm101-ubuntu/docbr0-opnsense-routing.md](../guests/vm101-ubuntu/docbr0-opnsense-routing.md) | + +Weitere Docker-Hosts: gleiches Muster — eigenes Subnetz wählen, der **Host** wird Gateway (`.1` der Bridge), OPNsense-Route zeigt auf die **Mgmt-IP** des Hosts. + +--- + +## Siehe auch + +| Dokument | Inhalt | +|----------|--------| +| [infrastruktur-netzwerk.md](infrastruktur-netzwerk.md) | VLANs, Proxmox, OPNsense-Rollen | +| [guests/vm101-ubuntu/README.md](../guests/vm101-ubuntu/README.md) | Stacks + docbr0-IP-Tabelle | +| [pve1/scripts/vm101-docker-nat-rules.sh](../pve1/scripts/vm101-docker-nat-rules.sh) | Container-Internet bei `iptables: false` |