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

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: Geräte im Netz und Internet-Tempo
WireGuard-Geräte 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 öffentlich einsehbar (Lizenz PolyForm Shield 1.0.0): github.com/Tuxxler/nzblab-agent.

Unraid
TrueNAS SCALE
Synology
Linux
Docker

Unraid

Unraid › Apps › nach «NASlab-Agent» suchen › Install.
Nicht gefunden? Unraid › Docker › ganz unten «Template repositories»: https://github.com/Tuxxler/nzblab-agent einfügen › Save. Dann Docker › Add Container › Vorlage «nzblab-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.
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

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
      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
    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
      PUID: "0"
      PGID: "0"
      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
    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.

Auf Synology bleibt der Agent root, weil DSM die Freigaben über ACLs regelt, die im Container keinem Benutzer entsprechen. Alle NAS-Pfade sind trotzdem 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-agent die Datei docker-compose.yml mit dem Text unten speichern.
Die Zeile mit /srv anpassen: 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
      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.yml mit dem Text unten speichern.
Pfad /mnt/user durch 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
      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 http://<NAS-Adresse>:8099 eine Übersicht (nur Anzeige); sie fragt ebenfalls nach dem Token.

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.