jean/docu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doku: allgemeines OPNsense-Docker-Routing-How-To in shared.

Browse Source 
VM-101-Instanz verweist auf shared; Duplikate reduziert.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
root
2026-06-28 11:14:24 +02:00
parent f3409ec675
commit fbf62e6e48
7 changed files with 258 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files
shared/infrastruktur-netzwerk.md
+1 -1
View File
@@ -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
shared/opnsense-docker-subnet-routing.md
+210
View File
@@ -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/<gast>/… 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` |