docu/shared/opnsense-docker-subnet-routing.md

# 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: 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](../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](infrastruktur-netzwerk.md) | VLANs, Proxmox, OPNsense-Rollen |
| [pve1/guests/vm101-ubuntu/README.md](../pve1/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` |