root
805b6d3534
Verlinkungen angepasst; pve2/guests als Platzhalter. Co-authored-by: Cursor <cursoragent@cursor.com>
6.5 KiB
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)
Compose-Beispiel externes Netz:
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
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
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: pveX/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 |
pve1/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 | VLANs, Proxmox, OPNsense-Rollen |
| pve1/guests/vm101-ubuntu/README.md | Stacks + docbr0-IP-Tabelle |
| pve1/scripts/vm101-docker-nat-rules.sh | Container-Internet bei iptables: false |