NASlab-Agent installieren
Früher NZBLab-Agent. Container, Image und Ordner heissen weiter nzblab-agent.
Unraid, TrueNAS SCALE, Synology, Linux oder Docker · etwa 5 Minuten
Neu: Bebilderte Schritt-für-Schritt-Anleitung für Unraid, Synology, TrueNAS und Linux.
Der Agent ist ein kleiner Container auf deinem NAS. Er misst rund um die Uhr, alle 30 Sekunden: Temperaturen, CPU, Grafikchip, Arbeitsspeicher, Plattenzugriffe und welche Programme Last machen. So hat die App auch dann Verlauf, wenn das Handy schläft.
Der Agent ist kostenlos, Quellcode öffentlich einsehbar. Diese Funktionen der App gibt es nur mit ihm; ohne Agent erscheinen sie einfach nicht:
- Verlauf ohne Lücken: Temperaturen, CPU, Grafikchip, Arbeitsspeicher
- Plattenzugriffe: wann eine Platte anläuft und welche Programme gerade liefen
- «Heute auf dem NAS»: die letzten 24 Stunden in einer Liste
- Cache und Mover pro Freigabe, appdata-Grösse pro Container
- Duplikate und Bestandsliste der Filme und Serien
- Heimnetz: Internet-Tempo und, wenn du es einschaltest, die Geräte im Netz (standardmässig aus)
- WireGuard-Geräte (Namen nur mit einem zusätzlichen, nur lesenden Pfad) und Plattenpreise
- Übersicht im Browser (nur Anzeige)
Nur lesen. Alle Ordner des NAS sind nur lesend eingebunden, schreiben darf der Agent nur in seinen eigenen Ordner (Verlauf und Token). Nach dem Start läuft er ohne root-Rechte. Image: ghcr.io/tuxxler/nzblab-agent:latest (amd64 und arm64). Quellcode offen (Open Source, Lizenz GNU AGPL-3.0): github.com/Tuxxler/nzblab-agent.
Unraid
- Unraid › Apps › nach «NASlab-Agent» suchen › Install.
- Nicht gefunden? Unraid › Docker › ganz unten «Template repositories»:
https://github.com/Tuxxler/unraid-templateseinfügen › Save. Dann Docker › Add Container › Vorlage «NASlab-Agent». - Pfade prüfen: alle Host-Pfade stehen auf «Read Only». Hast du keinen Pool «cache», den Pfad «Cache pool» entfernen.
- Pfad «Data (/config)» →
/mnt/user/appdata/nzblab-agent(Lesen/Schreiben) unbedingt behalten: Hier speichert der Agent Token und Verlauf, sonst gibt es nach jedem Update einen neuen Token. - Optional: Für Namen von WireGuard-Geräten den Zusatzpfad
/boot/config/wireguard(nur lesend) angeben; die Dateien enthalten auch den privaten WireGuard-Schlüssel des NAS, der Agent gibt ihn nie weiter. Ohne diesen Pfad fehlen nur die Namen. - Apply. Unraid lädt das Image und startet den Agenten.
Token: Unraid › Docker › Symbol von nzblab-agent › Logs. Die Zeile mit «Agent Token: …» steht dort nach dem ersten Start. Später: Datei appdata/nzblab-agent/token.txt.
TrueNAS SCALE
Der Agent läuft ab TrueNAS SCALE 24.10. Die App selbst spricht die TrueNAS-Schnittstelle erst ab Version 25.04 an.
- TrueNAS › Apps › Discover Apps › ⋮ oben rechts › Install via YAML.
- Name «nzblab-agent», den Text unten einfügen. «tank» durch den Namen deines Pools ersetzen.
- Save. TrueNAS lädt das Image und startet den Agenten.
services:
nzblab-agent:
image: ghcr.io/tuxxler/nzblab-agent:latest
container_name: nzblab-agent
restart: unless-stopped
ports:
- "8099:8099"
environment:
# TZ: Europe/Zurich # Beispiel: nur setzen, wenn die Zeit im Log falsch ist; eigene Zeitzone eintragen
PUID: "568"
PGID: "568"
FILES_EXCLUDE: "ix-applications,.ix-apps,.system,apps"
CACHE_ROOTS: ""
volumes:
- /mnt/tank/apps/nzblab-agent:/config
- /sys:/host/sys:ro
- /proc:/host/proc:ro
- /mnt/tank:/host/mnt/user:ro
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
cap_add:
- CHOWN
- DAC_OVERRIDE
- FOWNER
- SETUID
- SETGID
security_opt:
- no-new-privileges:true
mem_limit: 512m
cpus: 1.0
Token: TrueNAS › Apps › Installed › nzblab-agent › Workloads › Logs. Die Zeile mit «Agent Token: …» steht dort nach dem ersten Start. Später: Datei apps/nzblab-agent/token.txt in deinem Pool.
Synology
- File Station: im Ordner «docker» den Ordner «nzblab-agent» anlegen.
- Container Manager › Projekt › Erstellen: Name «nzblab-agent», Pfad
/docker/nzblab-agent, Quelle «docker-compose.yml erstellen», den Text unten einfügen. - Weiter › Fertig. Der Container startet von selbst.
services:
nzblab-agent:
image: ghcr.io/tuxxler/nzblab-agent:latest
container_name: nzblab-agent
restart: unless-stopped
ports:
- "8099:8099"
environment:
# TZ: Europe/Zurich # Beispiel: nur setzen, wenn die Zeit im Log falsch ist; eigene Zeitzone eintragen
PUID: "1026" # deine DSM-Nummer (SSH: id), 1026 ist nur ein Beispiel
PGID: "100"
FILES_EXCLUDE: "@*,#*,docker"
CACHE_ROOTS: ""
volumes:
- /volume1/docker/nzblab-agent:/config
- /sys:/host/sys:ro
- /proc:/host/proc:ro
- /volume1:/host/mnt/user:ro
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
cap_add:
- CHOWN
- DAC_OVERRIDE
- FOWNER
- SETUID
- SETGID
security_opt:
- no-new-privileges:true
mem_limit: 512m
cpus: 1.0
Token: Container Manager › Container › nzblab-agent › Protokoll. Die Zeile mit «Agent Token: …» steht dort nach dem ersten Start. Später: Datei docker/nzblab-agent/token.txt.
Agent 1.17.0 kennt auf Synology DSM 7 die Platten (sata1 …): Zugriffe, Temperaturen und SMART erscheinen in der App. Bisher nur mit Synology DSM 7.2 in einer virtuellen Maschine geprüft, nicht auf echter Synology-Hardware.
Auf Synology läuft der Agent ab 1.19.0 nicht mehr als root. Trage bei PUID und PGID die Nummern deines DSM-Benutzers ein (per SSH: id); 1026 und 100 sind nur ein Beispiel. Dieser Benutzer braucht Leserecht auf die Ordner, die der Agent ansehen soll. root (PUID 0) ist nur nötig, wenn DSM-Berechtigungen (ACLs) sonst Ordner sperren, und wird abgeraten. Alle NAS-Pfade sind nur lesend eingebunden.
Linux-Server (Debian, Ubuntu …) · Beta
Für einen Linux-Server ohne eigene NAS-Oberfläche. In der App: Einstellungen › Server-Verbindungen › NAS-Server › Typ «Linux (Beta)». Übersicht und Speicher kommen vom Agenten (ab Version 1.14.0), Docker-Container steuert die App optional über Portainer (Zugriffstoken: Portainer › Mein Konto › Zugriffstoken › Token hinzufügen). Beta: nur mit Testdaten geprüft.
- Ordner anlegen und den Ordner für Token und Verlauf dem Agenten-Benutzer geben (65534, ohne Login):
mkdir -p ~/nzblab-agent/nzblab-agent-config && sudo chown 65534:65534 ~/nzblab-agent/nzblab-agent-config - In
~/nzblab-agentdie Dateidocker-compose.ymlmit dem Text unten speichern. - Die Zeile mit
/srvanpassen: Jeden Ordner, dessen Belegung die App zeigen soll, nur lesend unter/host/fs/<Name>einbinden. Das ganze System (/) nie einbinden, der Agent braucht es nicht. - Im Ordner starten:
docker compose up -d
services:
nzblab-agent:
image: ghcr.io/tuxxler/nzblab-agent:latest
container_name: nzblab-agent
restart: unless-stopped
network_mode: host
user: "65534:65534"
environment:
# TZ: Europe/Zurich # Beispiel: nur setzen, wenn die Zeit im Log falsch ist; eigene Zeitzone eintragen
FILES_ROOT: "/host/fs"
CACHE_ROOTS: ""
volumes:
- ./nzblab-agent-config:/config
- /sys:/host/sys:ro
- /proc:/host/proc:ro
- /etc/os-release:/host/os-release:ro
- /srv:/host/fs/data:ro
read_only: true
tmpfs:
- /tmp
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
mem_limit: 512m
cpus: 1.0
Token: docker logs nzblab-agent 2>&1 | grep "Agent Token". Später: Datei nzblab-agent-config/token.txt neben docker-compose.yml.
Netzwerk «host», damit der Agent die echten Netzwerkkarten des Servers sieht. Port 8099 nie ins Internet freigeben. Der Agent bekommt kein docker.sock; Docker läuft über Portainer. Er läuft ohne root und ohne Capabilities; nicht als root oder als deinen eigenen Benutzer starten.
Docker (anderes Linux-NAS)
- Einen Ordner anlegen und darin die Datei
docker-compose.ymlmit dem Text unten speichern. - Pfad
/mnt/userdurch den Ordner mit deinen Dateien ersetzen (bleibt nur lesend). - Im Ordner starten:
docker compose up -d
services:
nzblab-agent:
image: ghcr.io/tuxxler/nzblab-agent:latest
container_name: nzblab-agent
restart: unless-stopped
ports:
- "8099:8099"
environment:
# TZ: Europe/Zurich # Beispiel: nur setzen, wenn die Zeit im Log falsch ist; eigene Zeitzone eintragen
PUID: "99"
PGID: "100"
volumes:
- ./nzblab-agent:/config
- /sys:/host/sys:ro
- /proc:/host/proc:ro
- /mnt/user:/host/mnt/user:ro
read_only: true
tmpfs:
- /tmp
security_opt:
- no-new-privileges:true
mem_limit: 512m
cpus: 1.0
Token: docker logs nzblab-agent 2>&1 | grep "Agent Token". Später: Datei nzblab-agent/token.txt neben docker-compose.yml.
Mit der App verbinden
- In der App: Einstellungen › Server-Verbindungen › NASlab-Agent › «Agent installieren: Anleitung und Suche».
- «Suchen» antippen: Die App fragt auf deinem NAS Port 8099 ab und trägt die Adresse ein.
- Token einfügen › «Speichern und testen».
Im Browser zeigt https://<NAS-Adresse>:8099 eine Übersicht (nur Anzeige); sie fragt ebenfalls nach dem Token. Der Browser warnt einmal, weil der Agent ein eigenes Zertifikat benutzt: Vergleiche den Fingerabdruck mit der Zeile im Container-Log.
Einrichtung innert 30 Minuten: Der Agent gibt die Schlüssel deiner Dienste (Sonarr, Radarr …) nur in den ersten 30 Minuten nach dem Start heraus und nur über HTTPS. Verbinde die App in dieser Zeit; sonst starte den Container neu. Wurden schon einmal Schlüssel ausgegeben, öffnet ein Neustart das Fenster ab Agent 1.20.1 nicht mehr: Lege dann im Ordner appdata/nzblab-agent die leere Datei keys-unlock an (10 Minuten offen). Ab Agent 1.20 gilt die Adresse https://<NAS-Adresse>:8099; ältere App-Versionen nutzen weiter http://.
Häufige Fragen
Wozu der Token?
Er schützt die Werte des Agenten: Ohne ihn liefert der Agent nichts ausser «ich lebe». Beim ersten Start erzeugt der Agent einen zufälligen Token und schreibt ihn genau einmal ins Container-Log, danach nur noch in die Datei token.txt. Neuer Token: token.txt löschen und den Container neu starten.
Nach jedem Update ein neuer Token?
Dann fehlt der Pfad /config. Unraid › Docker › nzblab-agent › Bearbeiten › Pfad /config → /mnt/user/appdata/nzblab-agent (Lesen/Schreiben) › Übernehmen. Ab Agent 1.13.0 warnt der Agent im Log und auf der Browser-Übersicht, wenn der Pfad fehlt.
Von unterwegs?
Port 8099 nie ins Internet freigeben. Über ein VPN wie WireGuard oder Tailscale verbinden, dann gilt dieselbe Adresse wie zu Hause.
Die Suche findet nichts
Läuft der Container? Bist du im Heimnetz oder per VPN verbunden? Steht im Container-Log «Agent … auf Port 8099»? Unter Unraid muss der Port 8099 frei sein.
Container-Namen oder appdata-Grössen fehlen
Diese Dateien darf nur root lesen. Variable PUID auf 0 setzen; die NAS-Pfade bleiben nur lesend.
Geräte im Heimnetz fehlen (Unraid)
Im Netzwerktyp «Bridge» sperrt Docker die Geräte-Tabelle. Mit «Host» sieht der Agent sie. Das ist freiwillig. Zusätzlich muss die Suche mit NZBLAB_LAN=1 eingeschaltet sein (standardmässig aus); sie schickt alle 30 Minuten ein leeres UDP-Paket an jede Adresse deines Heimnetzes, ein Router kann das als Portscan melden.