Portainer Agent über Wireguard VPN mit Unraid verbinden

Inhaltsverzeichnis

Dieser Leitfaden beschreibt, wie ein Portainer Agent über ein WireGuard VPN mit einem Unraid-Server verbunden wird.
Der Agent läuft auf einem externen Linux-Server (z. B. VPS oder dedizierter Host), während Portainer selbst auf dem Unraid-System betrieben wird. Die Kommunikation erfolgt ausschließlich über einen verschlüsselten VPN-Tunnel.

Voraussetzungen
#

Linux-Server mit Docker oder Docker Compose
Unraid-Server mit Portainer (CE oder BE)
UDP-Port 51820 muss extern erreichbar sein
Grundkenntnisse im Umgang mit Docker und UFW

Docker Compose auf dem Server
#

Erstelle eine Datei docker-compose.yml auf dem Zielserver mit folgendem Inhalt:

services:
  wireguard:
    image: lscr.io/linuxserver/wireguard:latest
    container_name: wireguard
    restart: always
    network_mode: host
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Berlin
      - SERVERURL=<ip-of-server>
      - SERVERPORT=51820
      - PEERS=1
      - PEERDNS=auto
    volumes:
      - ./wireguard:/config
      - /lib/modules:/lib/modules

  portainer-agent:
    image: portainer/agent:latest
    container_name: portainer-agent
    restart: always
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
      - /:/host

Hinweise:

Achte auf den korrekten Pfad /lib/modules (nicht /lib/nodules).
Setze SERVERURL auf die öffentliche IP oder DNS-Adresse des Servers.
Wenn mehrere Peers benötigt werden, kann PEERS entsprechend erhöht werden.

Container starten:

docker compose up -d

Docker von automatischen iptables-Regeln abhalten
#

Standardmäßig ändert Docker beim Start iptables-Regeln und öffnet Ports automatisch. Das kann dazu führen, dass Container-Ports trotz aktivem UFW öffentlich erreichbar sind. Um die Kontrolle vollständig bei UFW zu belassen, muss dieses Verhalten deaktiviert werden.

Erstelle oder bearbeite die Datei /etc/docker/daemon.json:

sudo mkdir -p /etc/docker
sudo nano /etc/docker/daemon.json

Inhalt:

{
  "iptables": false
}

Docker neu starten:

sudo systemctl restart docker

Überprüfen:

docker info | grep IPTables

Erwartete Ausgabe:

IPTables: false

Ab jetzt werden keine iptables-Regeln mehr automatisch hinzugefügt. Die Firewall-Regeln müssen vollständig manuell verwaltet werden, was in dieser Konfiguration über UFW erfolgt.

Firewall-Konfiguration (UFW)
#

WireGuard und der Portainer-Agent benötigen Zugriff über ihre jeweiligen Ports. Öffne die folgenden Ports und Interfaces gezielt:

sudo ufw allow 51820/udp
sudo ufw allow in on wg0 to any port 9001 proto tcp
sudo ufw deny in on docker0 from any to any
sudo ufw reload

Damit ist der Portainer-Agent nur über das VPN-Interface (wg0) und nicht über das öffentliche Interface (eth0) erreichbar. Die docker0-Bridge ist zusätzlich blockiert, um Container ohne host networking vollständig vom externen Netzwerk zu isolieren.

Überprüfe die aktiven Regeln:

sudo ufw status verbose

WireGuard-Client in Unraid einrichten
#

Nach dem Start des WireGuard-Containers auf dem Server wird im Volume-Verzeichnis eine Peer-Konfiguration generiert, z. B.:

./wireguard/peer1/peer1.conf

Diese Datei enthält den privaten Schlüssel und die Netzwerkparameter für den Client. Kopiere die Datei auf das Unraid-System und importiere sie unter:

Settings → VPN Manager → Add Tunnel → Import tunnel from file

Nach dem Import kann die Verbindung aktiviert werden. Prüfe auf Unraid die aktive Verbindung mit:

wg show

Beispielausgabe:

peer: <PublicKey>
endpoint: <server-ip>:51820
allowed ips: 10.13.13.0/24
latest handshake: 10 seconds ago
transfer: 12.1 KiB received, 8.4 KiB sent

Wenn keine Verbindung aufgebaut wird, überprüfe die Firewall, Ports und Container-Logs.

Verbindung zum Portainer-Agenten herstellen
#

Nach erfolgreicher VPN-Verbindung kann der Portainer-Agent über seine WireGuard-IP erreicht werden. Standardmäßig nutzt das LinuxServer.io-WireGuard-Image das Subnetz 10.13.13.0/24, wobei der Server meist die IP 10.13.13.1 erhält.

In Portainer (auf Unraid):

Öffne Environments → Add Environment → Agent
Trage als Agent Address ein:
```
10.13.13.1:9001
```
Speichern und Verbindung testen.

Wenn die Verbindung erfolgreich ist, sollte der neue Remote-Agent in der Übersicht erscheinen.

Fehlerbehebung
#

VPN-Verbindung wird nicht hergestellt:

Logs prüfen: docker logs wireguard
Firewall-Regeln prüfen: sudo ufw status
Sicherstellen, dass UDP 51820 erreichbar ist.

Agent ist über Portainer nicht erreichbar:

Test mit ping 10.13.13.1 oder nc -zv 10.13.13.1 9001
Container-Status prüfen: docker ps
PersistentKeepalive = 25 in der Peer-Konfiguration setzen, falls die Verbindung regelmäßig abbricht.

Falsche IP oder Subnetz:

Das Subnetz kann in der wireguard/config/wg0.conf angepasst werden.
Nach Änderungen Container neu starten.

Beispielverzeichnis
#

/opt/portainer-vpn/
├── docker-compose.yml
└── wireguard/
    ├── server.conf
    ├── peer1/
    │   └── peer1.conf

Zusammenfassung
#

Mit dieser Konfiguration läuft der Portainer-Agent sicher hinter einem WireGuard-VPN-Tunnel. Docker öffnet keine Ports automatisch, und der gesamte Netzwerkverkehr wird über UFW kontrolliert. Der Agent ist ausschließlich über das VPN-Interface erreichbar, wodurch die Verwaltung von Remote-Docker-Hosts über Portainer sicher und reproduzierbar erfolgt.

Autor

Florian Hoss

Voraussetzungen#

Docker Compose auf dem Server#

Docker von automatischen iptables-Regeln abhalten#

Firewall-Konfiguration (UFW)#

WireGuard-Client in Unraid einrichten#

Verbindung zum Portainer-Agenten herstellen#

Fehlerbehebung#

Beispielverzeichnis#

Zusammenfassung#