+49 8431 - 536737-0 info@datazone.de WhatsApp EN
Fernwartung Download starten

TrueNAS REST API: Automatisierung und Integration für Storage-Profis

TrueNASStorageMonitoring
TrueNAS REST API: Automatisierung und Integration für Storage-Profis

Die Weboberfläche von TrueNAS ist komfortabel — doch wer Dutzende Datasets verwaltet, regelmäßig Snapshots prüft oder Replikationsjobs über mehrere Standorte steuert, stößt schnell an die Grenzen manueller Verwaltung. Die TrueNAS REST API ermöglicht die vollständige Automatisierung aller Storage-Operationen: programmatisch, reproduzierbar und integrationsfähig mit bestehenden Monitoring- und Orchestrierungssystemen.

API-Zugang einrichten

API-Key erstellen

Seit TrueNAS CORE 12 und TrueNAS SCALE steht ein Token-basiertes Authentifizierungssystem zur Verfügung. Der API-Key ersetzt Benutzername und Passwort bei API-Aufrufen und lässt sich jederzeit widerrufen.

Erstellen Sie den Key über die Weboberfläche unter Settings > API Keys > Add:

  1. Vergeben Sie einen aussagekräftigen Namen (z. B. monitoring-prod-01)
  2. Kopieren Sie den generierten Key sofort — er wird nur einmal angezeigt
  3. Speichern Sie den Key in einem Passwort-Manager oder Vault

Alternativ per CLI auf TrueNAS SCALE:

midclt call api_key.create '{"name": "monitoring-prod-01"}'

Basis-URL und Authentifizierung

Die API ist unter https://<truenas-ip>/api/v2.0/ erreichbar. Alle Endpunkte erwarten den API-Key im Authorization-Header:

curl -k -H "Authorization: Bearer <API-KEY>" \
  https://192.168.1.50/api/v2.0/system/info

Die Antwort liefert JSON mit Systeminformationen: Version, Hostname, Uptime und Hardware-Details. Der -k-Parameter überspringt die Zertifikatsprüfung — in Produktivumgebungen sollten Sie ein gültiges TLS-Zertifikat verwenden.

Datasets verwalten

Datasets auflisten

curl -k -H "Authorization: Bearer <API-KEY>" \
  https://192.168.1.50/api/v2.0/pool/dataset

Die Antwort enthält alle Datasets mit ihren Eigenschaften: Quota, Compression, Mountpoint und aktuelle Belegung.

Dataset erstellen

curl -k -X POST -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tank/backups/server-web-01",
    "compression": "zstd",
    "quota": 107374182400,
    "comments": "Backup-Target Web-Server Produktion"
  }' \
  https://192.168.1.50/api/v2.0/pool/dataset

Das Quota ist in Bytes angegeben — 107374182400 entspricht 100 GiB. Die API validiert automatisch, ob der Pool genügend Kapazität hat.

Dataset-Eigenschaften ändern

curl -k -X PUT -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{"quota": 214748364800}' \
  https://192.168.1.50/api/v2.0/pool/dataset/id/tank%2Fbackups%2Fserver-web-01

Wichtig: Der Dataset-Pfad in der URL muss URL-encoded sein — Schrägstriche werden zu %2F.

Snapshots automatisieren

Snapshot erstellen

curl -k -X POST -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "tank/backups/server-web-01",
    "name": "auto-2026-04-21-0200",
    "recursive": true
  }' \
  https://192.168.1.50/api/v2.0/zfs/snapshot

Snapshots auflisten und filtern

# Alle Snapshots eines Datasets
curl -k -H "Authorization: Bearer <API-KEY>" \
  "https://192.168.1.50/api/v2.0/zfs/snapshot?query-filters=[[\
  \"dataset\",\"=\",\"tank/backups/server-web-01\"]]"

Alte Snapshots bereinigen

Per API lassen sich Snapshots gezielt löschen. In Kombination mit einem Skript können Sie eine Retention-Policy implementieren:

import requests
from datetime import datetime, timedelta

TRUENAS_URL = "https://192.168.1.50/api/v2.0"
API_KEY = "1-xxxxxxxxxxxxxxxxxxxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
RETENTION_DAYS = 30

response = requests.get(
    f"{TRUENAS_URL}/zfs/snapshot",
    headers=HEADERS,
    verify=False,
    params={
        "query-filters": '[["dataset","=","tank/backups/server-web-01"]]',
        "query-options": '{"select": ["id", "name", "properties"]}'
    }
)

cutoff = datetime.now() - timedelta(days=RETENTION_DAYS)

for snap in response.json():
    creation = datetime.fromtimestamp(
        int(snap["properties"]["creation"]["parsed"])
    )
    if creation < cutoff:
        requests.delete(
            f"{TRUENAS_URL}/zfs/snapshot/id/{snap['id']}",
            headers=HEADERS,
            verify=False
        )
        print(f"Deleted: {snap['id']}")

Replikation steuern

Die Replikations-API erlaubt das Erstellen, Starten und Überwachen von Replikationsjobs zwischen TrueNAS-Systemen.

Replikationsjob anlegen

curl -k -X POST -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "offsite-backup-web",
    "direction": "PUSH",
    "transport": "SSH",
    "ssh_credentials": 1,
    "source_datasets": ["tank/backups/server-web-01"],
    "target_dataset": "backup-pool/offsite/server-web-01",
    "recursive": true,
    "auto": true,
    "retention_policy": "SOURCE",
    "schedule": {
      "minute": "0",
      "hour": "3",
      "dom": "*",
      "month": "*",
      "dow": "*"
    }
  }' \
  https://192.168.1.50/api/v2.0/replication

Replikationsstatus abfragen

curl -k -H "Authorization: Bearer <API-KEY>" \
  https://192.168.1.50/api/v2.0/replication/id/1

Die Antwort enthält state, last_snapshot, job_progress und errors — alle Informationen für ein automatisiertes Monitoring.

Alert-System per API

TrueNAS generiert Alerts für kritische Ereignisse: Pool-Degradierung, SMART-Fehler, Update-Verfügbarkeit oder Speicherknappheit. Diese Alerts lassen sich per API abfragen und in externe Systeme weiterleiten.

# Aktive Alerts abrufen
curl -k -H "Authorization: Bearer <API-KEY>" \
  https://192.168.1.50/api/v2.0/alert/list

# Alert als gelesen markieren
curl -k -X POST -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "alert-uuid-hier"}' \
  https://192.168.1.50/api/v2.0/alert/dismiss

Python-Wrapper für wiederkehrende Aufgaben

Für komplexere Automatisierungen empfiehlt sich ein Python-Wrapper, der Fehlerbehandlung und Logging integriert:

import requests
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("truenas-api")

class TrueNASAPI:
    def __init__(self, host, api_key, verify_ssl=False):
        self.base_url = f"https://{host}/api/v2.0"
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        })
        self.session.verify = verify_ssl

    def get_pools(self):
        resp = self.session.get(f"{self.base_url}/pool")
        resp.raise_for_status()
        return resp.json()

    def get_pool_health(self):
        pools = self.get_pools()
        results = {}
        for pool in pools:
            results[pool["name"]] = {
                "status": pool["status"],
                "healthy": pool["healthy"],
                "capacity": pool["size"],
                "allocated": pool["allocated"]
            }
        return results

    def create_snapshot(self, dataset, name, recursive=False):
        resp = self.session.post(
            f"{self.base_url}/zfs/snapshot",
            json={
                "dataset": dataset,
                "name": name,
                "recursive": recursive
            }
        )
        resp.raise_for_status()
        logger.info(f"Snapshot created: {dataset}@{name}")
        return resp.json()

    def get_alerts(self, dismissed=False):
        alerts = self.session.get(
            f"{self.base_url}/alert/list"
        ).json()
        if not dismissed:
            alerts = [a for a in alerts if not a["dismissed"]]
        return alerts

Webhook-Integration

Die Alert-Daten lassen sich per Webhook an Slack, Microsoft Teams oder beliebige HTTP-Endpunkte weiterleiten:

import json
import requests

def forward_alerts_to_slack(truenas_api, slack_webhook_url):
    alerts = truenas_api.get_alerts()
    for alert in alerts:
        if alert["level"] in ("CRITICAL", "ERROR"):
            payload = {
                "text": f":warning: *TrueNAS Alert*\n"
                        f"*Level:* {alert['level']}\n"
                        f"*Message:* {alert['formatted']}\n"
                        f"*Source:* {alert['source']}"
            }
            requests.post(
                slack_webhook_url,
                json=payload
            )

Für Microsoft Teams ersetzen Sie das Payload-Format durch eine Adaptive Card. Die Logik bleibt identisch.

Monitoring-Anbindung: Zabbix

Zabbix kann die TrueNAS-API direkt über HTTP-Agent-Items abfragen. Erstellen Sie ein Template mit folgenden Items:

ItemEndpunktTypIntervall
Pool Status/api/v2.0/poolHTTP Agent5 min
Alert Count/api/v2.0/alert/listHTTP Agent1 min
Replication Status/api/v2.0/replicationHTTP Agent5 min
System Info/api/v2.0/system/infoHTTP Agent15 min

Die JSON-Antworten lassen sich mit Zabbix-Preprocessing (JSONPath) in einzelne Metriken zerlegen:

  • $..[?(@.name=="tank")].status extrahiert den Pool-Status
  • $.length() zählt die aktiven Alerts
  • $..[?(@.name=="offsite-backup-web")].state.state liefert den Replikationsstatus

Monitoring-Anbindung: Prometheus

Für Prometheus existiert der Community-Exporter truenas-exporter, alternativ lässt sich ein eigener Exporter mit wenigen Zeilen Python erstellen:

from prometheus_client import start_http_server, Gauge
import time

pool_status = Gauge(
    "truenas_pool_healthy", "Pool health status", ["pool"]
)
pool_used = Gauge(
    "truenas_pool_used_bytes", "Pool used bytes", ["pool"]
)
alert_count = Gauge(
    "truenas_active_alerts", "Number of active alerts"
)

def collect_metrics(api):
    for name, health in api.get_pool_health().items():
        pool_status.labels(pool=name).set(1 if health["healthy"] else 0)
        pool_used.labels(pool=name).set(health["allocated"])
    alert_count.set(len(api.get_alerts()))

if __name__ == "__main__":
    api = TrueNASAPI("192.168.1.50", "1-xxxxxxxxxxxx")
    start_http_server(9150)
    while True:
        collect_metrics(api)
        time.sleep(60)

Die Metriken stehen dann unter http://exporter:9150/metrics zur Verfügung und lassen sich in Grafana visualisieren.

Best Practices

  • API-Keys rotieren: Erstellen Sie regelmäßig neue Keys und widerrufen Sie alte
  • Rate Limiting beachten: TrueNAS hat kein integriertes Rate Limiting — bauen Sie Pausen in Batch-Skripte ein
  • Fehlerbehandlung: Prüfen Sie HTTP-Statuscodes und implementieren Sie Retries mit Backoff
  • TLS verwenden: Ersetzen Sie das selbstsignierte Zertifikat durch ein gültiges Zertifikat (Let’s Encrypt oder interne CA)
  • Audit-Trail: Loggen Sie alle API-Aufrufe mit Zeitstempel und Ergebnis

Häufig gestellte Fragen

Welche TrueNAS-Versionen unterstützen die REST API?

Die v2.0 API ist seit TrueNAS CORE 12.0 und TrueNAS SCALE 22.02 verfügbar. Ältere FreeNAS-Versionen verwenden die v1.0 API mit anderem Endpunkt-Schema.

Kann ich die API über das Internet erreichbar machen?

Davon raten wir dringend ab. Nutzen Sie stattdessen einen VPN-Tunnel oder einen Reverse-Proxy mit Authentifizierung. Die API bietet vollen Zugriff auf alle Storage-Operationen — ein kompromittierter Key kann das gesamte System zerstören.

Wie finde ich die verfügbaren Endpunkte?

TrueNAS liefert eine interaktive API-Dokumentation unter https://<truenas-ip>/api/docs/. Dort sind alle Endpunkte mit Parametern, Beispielen und Antwortformaten dokumentiert.

Sie möchten Ihre TrueNAS-Infrastruktur automatisieren? Kontaktieren Sie uns — wir integrieren TrueNAS in Ihre bestehende Monitoring- und Automatisierungslandschaft.

Mehr zu diesen Themen:

TrueNAS Enterprise Storage

Weitere Artikel

Backup-Strategie für KMU: Proxmox PBS + TrueNAS als zuverlässiges Backup-Konzept

Backup-Strategie für KMU mit Proxmox PBS und TrueNAS: 3-2-1-Regel umsetzen, PBS als primäres Backup-Target, TrueNAS-Replikation als Offsite-Kopie, Retention Policies und automatisierte Restore-Tests.

Proxmox Notification-System: Matcher, Targets, SMTP, Gotify und Webhooks

Proxmox Notification-System ab PVE 8.1 konfigurieren: Matcher und Targets, SMTP-Setup, Gotify-Integration, Webhook-Targets, Notification-Filter und sendmail vs. neue API.

TrueNAS mit MCP: KI-gestützte NAS-Verwaltung per natürlicher Sprache

TrueNAS mit MCP (Model Context Protocol) verbinden: KI-Assistenten für NAS-Verwaltung, Status-Abfragen, Snapshot-Erstellung per Chat, Sicherheitsaspekte und Zukunftsausblick.

Zurück zur Übersicht

IT-Beratung gewünscht?

Kontaktieren Sie uns für eine unverbindliche Beratung zu Proxmox, OPNsense, TrueNAS und mehr.

Jetzt Kontakt aufnehmen