TrueNAS API mit Python: Eigene Reports automatisieren

TrueNAS bietet seit Jahren eine umfangreiche API. Was lange WebSocket-only war, ist seit SCALE auch über klassische REST erreichbar — und ab den 24er-Releases stabil dokumentiert. Wer Reports automatisieren, Monitoring-Daten ziehen oder Lifecycle-Operations skripten will, braucht keinen Klick durch die WebUI mehr.

Dieser Artikel zeigt konkret, was mit der API geht: API-Key generieren, drei typische Reports ziehen (Pool-Auslastung, Snapshot-Alter, SMART-Status) und ein vollständiges Skript für einen 80%-Pool-Alert per E-Mail. Wer einen Einstieg in TrueNAS-API-Automatisierung sucht, findet hier den praktischen Teil.

WebSocket oder REST? Was wann?

TrueNAS SCALE bietet zwei API-Geschmacksrichtungen:

API	Endpunkt	Eigenschaft
WebSocket (JSON-RPC)	wss://truenas/websocket	Echte Realtime, eventbasiert, voller Funktionsumfang
REST	https://truenas/api/v2.0/	Stateless, einfacher Einstieg, gut für Skripte

Für Scripted Reports ist REST meist die bessere Wahl: Schneller einstieg, kein Session-Handling, klassische HTTP-Bibliotheken. Für Realtime-Events (z.B. ein Dashboard, das auf Snapshot-Erstellungen reagiert) ist WebSocket richtig. Dieser Artikel zeigt REST, weil es für den typischen Report-Use-Case kürzer und robuster ist.

API-Key generieren

In TrueNAS unter Credentials -> API Keys -> Add:

• Name: z.B. python-reports
• Reset Token: bei späteren Bedarfen
• Zugriff: auf wenige Endpoints einschränken, wenn möglich

Der API-Key wird einmalig angezeigt und sollte sofort in den eigenen Secret-Manager kopiert werden — danach lässt er sich nicht mehr auslesen.

Best Practice:

• Pro Skript / Service ein eigener API-Key, mit sprechendem Namen
• Keys regelmässig rotieren (jährlich)
• Keys nie im Code committen — .env, Vault oder Umgebungsvariablen verwenden
• Bei Verlust sofort revoken (in derselben UI)

Hello World: Pool-Auslastung abfragen

Die einfachste Abfrage — wie voll ist der Pool?

import os
import requests

TRUENAS_HOST = "https://truenas.example.com"
API_KEY = os.environ["TRUENAS_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# requests.get ohne verify=False — TLS-Zertifikat sollte gueltig sein
resp = requests.get(f"{TRUENAS_HOST}/api/v2.0/pool", headers=HEADERS, timeout=30)
resp.raise_for_status()

for pool in resp.json():
    used = pool["used"]["parsed"]      # Bytes
    total = pool["size"]["parsed"]     # Bytes
    pct = used / total * 100
    print(f"Pool {pool['name']}: {pct:.1f}% belegt ({used / 1e12:.2f} TB / {total / 1e12:.2f} TB)")

Ausgabe-Beispiel:

Pool tank: 67.4% belegt (24.31 TB / 36.07 TB)
Pool fastpool: 41.2% belegt (3.30 TB / 8.00 TB)

Beispiel 1: Snapshot-Alter pro Dataset

Snapshots sind nützlich, solange sie automatisch rotieren — aber wenn ein Snapshot-Task hängt, sammeln sich Snapshots oder die letzten Snapshots werden zu alt. Folgendes Skript meldet die ältesten Snapshots pro Dataset:

import os
import requests
from datetime import datetime, timezone

TRUENAS_HOST = "https://truenas.example.com"
HEADERS = {"Authorization": f"Bearer {os.environ['TRUENAS_API_KEY']}"}

resp = requests.get(
    f"{TRUENAS_HOST}/api/v2.0/zfs/snapshot",
    headers=HEADERS,
    params={"limit": 0},
    timeout=60,
)
resp.raise_for_status()
snapshots = resp.json()

# nach Dataset gruppieren und neuesten Snapshot pro Dataset finden
latest = {}
for snap in snapshots:
    ds = snap["dataset"]
    ts = snap["properties"]["creation"]["parsed"]   # Unix-Timestamp
    if ds not in latest or ts > latest[ds]:
        latest[ds] = ts

now = datetime.now(tz=timezone.utc).timestamp()
print(f"{'Dataset':40} {'Letzter Snap':25} {'Alter':10}")
for ds, ts in sorted(latest.items()):
    dt = datetime.fromtimestamp(ts, tz=timezone.utc)
    age_h = (now - ts) / 3600
    flag = " <-- alt!" if age_h > 48 else ""
    print(f"{ds:40} {dt.isoformat():25} {age_h:6.1f} h{flag}")

Wer das Skript per Cron einmal täglich laufen lässt und die Ausgabe in ein Monitoring oder eine Mail leitet, hat ein einfaches Snapshot-Health-Monitoring.

Beispiel 2: SMART-Status aller Disks

Disk-Defekte lassen sich oft Tage vorher in SMART-Werten erkennen. Die API gibt den SMART-Status pro Disk zurück:

import os
import requests

TRUENAS_HOST = "https://truenas.example.com"
HEADERS = {"Authorization": f"Bearer {os.environ['TRUENAS_API_KEY']}"}

resp = requests.get(f"{TRUENAS_HOST}/api/v2.0/disk", headers=HEADERS, timeout=30)
resp.raise_for_status()

for disk in resp.json():
    name = disk["name"]
    model = disk.get("model", "")
    serial = disk.get("serial", "")
    # SMART-Status via separatem Endpunkt
    smart = requests.get(
        f"{TRUENAS_HOST}/api/v2.0/smart/test/results",
        headers=HEADERS,
        params={"disk": name},
        timeout=30,
    ).json()
    last = smart[0] if smart else None
    last_status = last["status"] if last else "no-test"
    flag = " <-- FAIL" if last and last["status"] != "SUCCESS" else ""
    print(f"{name:8} {model[:20]:20} SN={serial[:14]:14} last={last_status:10}{flag}")

Das Skript listet alle Disks plus letztes SMART-Test-Ergebnis. Disks ohne Test in den letzten 90 Tagen oder mit Fail-Status sind die ersten Kandidaten für einen genaueren Blick — gerne ergänzt mit smartctl -a lokal auf TrueNAS.

Vollständiges Skript: 80%-Pool-Alert per E-Mail

Das Praxis-Beispiel: täglich prüfen, ob ein Pool über 80% Auslastung liegt, und im Ernstfall eine Mail an die IT schicken.

#!/usr/bin/env python3
"""TrueNAS Pool-Auslastungs-Alert.

Liest Pool-Auslastung ueber die TrueNAS-REST-API und schickt eine Mail,
wenn ein Pool ueber dem Schwellwert liegt.
"""
import os
import smtplib
import sys
from email.mime.text import MIMEText

import requests

TRUENAS_HOST = os.environ["TRUENAS_HOST"]
API_KEY = os.environ["TRUENAS_API_KEY"]
THRESHOLD_PCT = float(os.environ.get("THRESHOLD_PCT", "80"))

SMTP_HOST = os.environ["SMTP_HOST"]
SMTP_PORT = int(os.environ.get("SMTP_PORT", "587"))
SMTP_USER = os.environ["SMTP_USER"]
SMTP_PASS = os.environ["SMTP_PASS"]
MAIL_FROM = os.environ["MAIL_FROM"]
MAIL_TO = os.environ["MAIL_TO"]

HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def get_pools():
    resp = requests.get(
        f"{TRUENAS_HOST}/api/v2.0/pool",
        headers=HEADERS,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()


def send_alert(subject, body):
    msg = MIMEText(body)
    msg["Subject"] = subject
    msg["From"] = MAIL_FROM
    msg["To"] = MAIL_TO
    with smtplib.SMTP(SMTP_HOST, SMTP_PORT) as smtp:
        smtp.starttls()
        smtp.login(SMTP_USER, SMTP_PASS)
        smtp.send_message(msg)


def main():
    pools = get_pools()
    alerts = []
    for pool in pools:
        used = pool["used"]["parsed"]
        total = pool["size"]["parsed"]
        pct = used / total * 100
        line = f"Pool {pool['name']}: {pct:.1f}% belegt ({used / 1e12:.2f} TB / {total / 1e12:.2f} TB)"
        print(line)
        if pct >= THRESHOLD_PCT:
            alerts.append(line)

    if alerts:
        body = "\n".join([
            f"Pool-Auslastung uebersteigt {THRESHOLD_PCT}% auf {TRUENAS_HOST}:",
            "",
            *alerts,
            "",
            "Bitte pruefen: TrueNAS WebUI -> Storage -> Pools.",
        ])
        send_alert(f"[TrueNAS] Pool-Auslastung >= {THRESHOLD_PCT}%", body)
        sys.exit(1)


if __name__ == "__main__":
    main()

Einsatz per Cron:

# einmal taeglich um 07:00
0 7 * * * /usr/bin/env -i \
  TRUENAS_HOST=https://truenas.example.com \
  TRUENAS_API_KEY=$(cat /etc/truenas-api.key) \
  THRESHOLD_PCT=80 \
  SMTP_HOST=mail.example.com \
  SMTP_PORT=587 \
  SMTP_USER=alerts@example.com \
  SMTP_PASS=$(cat /etc/smtp.pass) \
  MAIL_FROM=alerts@example.com \
  MAIL_TO=it@example.com \
  /usr/bin/python3 /opt/truenas/pool-alert.py

In der Praxis sollte das Skript nicht direkt im Cron stehen, sondern aus einem Wrapper-Script aufgerufen werden, das systemd-Journal-Logs sauber befüllt. Auch ein systemd-Timer ist sauberer als der reine Cron-Job.

Weitere praktische API-Endpoints

Endpoint	Use Case
/api/v2.0/replication	Replikations-Status aller Tasks
/api/v2.0/cloudsync/credentials	Cloud-Credentials für Audit
/api/v2.0/system/info	TrueNAS-Version, Uptime, Hostname
/api/v2.0/alert/list	aktuelle Alerts (WebUI-Glocke)
/api/v2.0/reporting/get_data	Performance-Metriken (CPU, IO, Netz)
/api/v2.0/user	User-Verwaltung
/api/v2.0/sharing/smb	SMB-Shares listen

Die komplette Endpoint-Liste findet sich in TrueNAS unter System Settings -> API Keys -> API Docs — TrueNAS dokumentiert die API direkt im UI.

Sicherheits- und Operations-Tipps

• TLS-Zertifikat zwingend gültig — kein verify=False in produktiven Skripten
• Rate-Limit beachten: Bei vielen Abfragen sammeln, statt jede Disk einzeln pollen
• API-Key-Scope minimieren: lieber drei Keys für drei Zwecke als ein Master-Key
• Logs: jede API-Aktion wird auf TrueNAS-Seite geloggt — Audit-Trail nutzen
• Error-Handling: timeouts, 401 (Key revoked), 503 (TrueNAS-Reboot) sauber behandeln
• Idempotenz: Skripte so bauen, dass mehrfach-Aufruf kein Schaden anrichtet (besonders bei POST/PUT)

Wann lohnt eigene Skripte vs. fertige Tools?

Szenario	Empfehlung
Standardmonitoring (CPU, Disk, Memory)	klassische Tools wie Zabbix
TrueNAS-spezifische Kennzahlen	API-Skripte, kein Zabbix-Plugin nötig
Compliance-Reports / Audit-Exports	API-Skripte mit definiertem Output-Format
Massen-Configuration	API-Skripte, idempotent, im Git
Einzel-Operations	TrueNAS WebUI weiter nutzen

Fazit

Die TrueNAS-API verwandelt das NAS von “Web-UI-only” in eine programmierbare Plattform. Drei Stunden Investment in ein paar Python-Skripte liefern Reports, die in der WebUI gar nicht existieren — und automatisieren Routinen, die sonst manuell laufen. Wer mehrere TrueNAS-Systeme betreibt oder Compliance-Reports regelmässig liefern muss, hat hier deutlich mehr Hebel als mit Klick-Routinen.

Wer mit eigener Automation einsteigen will, beginnt am besten mit einem Read-only-Use-Case (Reports). Wenn das robust läuft, kommen Write-Operations (z.B. Snapshot-Cleanup) dazu — immer mit ausführlichem Testen auf einer Test-Instanz, bevor produktive Systeme angesprochen werden.

Verwandte Artikel

• TrueNAS-API: Automatisierung und Integration
• Proxmox REST-API mit Python automatisieren
• Grafana und Prometheus: IT-Monitoring
• Zabbix: Open-Source-Monitoring