TrueNAS als iSCSI-Storage für Proxmox: das offizielle Plugin einrichten

Proxmox und TrueNAS gehören im Homelab fast schon zusammen. Bisher hieß das aber: ZVOLs von Hand anlegen, iSCSI-Extents klicken, LUNs zuordnen und hoffen, dass man nichts vergisst. Mit dem offiziellen TrueNAS-Proxmox-Plugin erledigt Proxmox das selbst über die TrueNAS-API.

Dieser Beitrag zeigt die Einrichtung Schritt für Schritt: erst die Vorbereitung auf TrueNAS, dann Installation und Konfiguration auf Proxmox.

#Die Ausgangslage

Komponente	Details
NAS	TrueNAS SCALE 25.10 „Goldeye“
Hypervisor	Proxmox VE
Protokoll	iSCSI über die TrueNAS-API
Ziel	Shared Storage für VM-Disks und Container

#Teil 1: TrueNAS vorbereiten

#Dataset anlegen

Unter Datasets → Add Dataset ein neues Dataset erstellen:

• Name: Proxmox-Backup
• Übergeordnetes Dataset: der Speicherpool, z. B. pve
• Dataset-Voreinstellung: Generic

Unter diesem Dataset legt das Plugin später alle ZVOLs für die VMs ab.

#iSCSI-Dienst aktivieren

System → Services, in der Zeile iSCSI auf den Play-Button klicken und Start Automatically anhaken.

#Base Name prüfen

In derselben Zeile über das Stift-Symbol die iSCSI Global Configuration öffnen. Wichtig ist hier der Base Name: Er muss mit iqn beginnen. Der Standardwert iqn.2005-10.org.freenas.ctl passt.

Den Wert notieren. Er landet später zusammen mit dem Target-Namen in der storage.cfg, im Format <Base Name>:<Target Name>.

#Target, Extent und Portal per Wizard

Unter Shares → Block (iSCSI) Shares Targets auf Wizard klicken. Der Assistent hat drei Schritte.

1. Target

Das Dropdown auf Create New lassen und einen Target-Namen vergeben, z. B. pve. Weiter.

2. Extent

• Name: beliebig
• Extent Type: Device
• Device: das ZVOL, das TrueNAS freigeben soll
• Sharing Platform: Modern OS (4K-Blockgröße, TPC an, kein Xen-Kompatibilitätsmodus, SSD-Speed)
• Read-Only: aus lassen

3. Protocol Options

• Portal: über Add ein Portal auf 0.0.0.0:3260 anlegen oder ein bestehendes wählen.
• Initiators: leer lassen bzw. Allow all initiators anhaken, damit alle Proxmox-Knoten zugreifen dürfen. Wer den Zugriff einschränken will, trägt hier die IQNs der Proxmox-Knoten ein.

Speichern, fertig.

Wer jedes Feld einzeln steuern möchte, findet den manuellen Weg über die Registerkarten Targets, Extents, Initiators, Portals und Authorized Access weiterhin unter /ui/sharing/iscsi/targets. Für den Normalfall reicht der Wizard.

#API-Schlüssel erstellen

Oben rechts im Benutzermenü (root) → My API Keys → Add. Den Schlüssel sofort kopieren, TrueNAS zeigt ihn nur ein einziges Mal an. Er kommt später als tn_api_key in die storage.cfg.

#Optional: CHAP

Wer CHAP nutzen möchte:

1. Im Wizard (Schritt 3) ein Portal wählen, dessen Discovery Auth Method auf CHAP steht.
2. Im manuellen Ablauf unter Authorized Access einen Eintrag mit Benutzer und einem 12–16 Zeichen langen Passwort anlegen.
3. In Proxmox tn_chap_user und tn_chap_password in der storage.cfg ergänzen.

#Teil 2: Proxmox einrichten

#Plugin installieren

Das Plugin kommt über das offizielle APT-Repository. Das Installskript richtet es ein:

bash <(curl -sSL https://raw.githubusercontent.com/truenas/truenas-proxmox-plugin/main/install.sh) --non-interactive --apt-install

Bei einem Cluster muss das Plugin auf jedem Knoten installiert werden.

#Storage konfigurieren

Die Konfiguration liegt in /etc/pve/storage.cfg und gilt dank Cluster-Dateisystem automatisch für alle Knoten:

nano /etc/pve/storage.cfg

Dort einen neuen Eintrag mit den Werten der eigenen TrueNAS-Umgebung ergänzen:

truenasplugin: truenas-storage
    tn_api_host 10.26.0.15
    tn_api_key <DEIN-API-SCHLÜSSEL>
    tn_api_insecure 1
    tn_target_iqn iqn.2005-10.org.freenas.ctl:pve
    tn_dataset pve/Proxmox-Backup
    tn_discovery_portal 10.26.0.15:3260
    content images,rootdir
    shared 1

Was die Zeilen bedeuten:

Parameter	Bedeutung
tn_api_host	IP oder Hostname von TrueNAS
tn_api_key	der API-Schlüssel von oben
tn_api_insecure	1 akzeptiert selbstsignierte Zertifikate
tn_target_iqn	Base Name + : + Target-Name
tn_dataset	Pfad des Datasets, unter dem die ZVOLs landen
tn_discovery_portal	IP und Port des iSCSI-Portals
content	images für VM-Disks, rootdir für Container
shared	1, damit alle Knoten den Storage nutzen (wichtig für Live-Migration)

#Was das Plugin ab jetzt erledigt

Ab hier übernimmt das Plugin. Sobald eine VM ihre erste Disk auf dem neuen Storage bekommt:

• legt es ein ZVOL unter dem Dataset an, z. B. pve/Proxmox-Backup/vm-100-disk-0,
• erstellt dafür einen iSCSI-Extent,
• ordnet den Extent dem Target unter einer eigenen LUN zu,
• und kümmert sich auf jedem Proxmox-Knoten um Auf- und Abbau der iSCSI-Sessions.

Kein Klicken in der TrueNAS-Oberfläche mehr, keine vergessenen LUNs. Der Storage taucht in Proxmox einfach als truenas-storage auf und verhält sich wie jeder andere.

#Fazit

Die meiste Arbeit steckt in der einmaligen iSCSI-Vorbereitung auf TrueNAS. Wer auf einen gültigen Base Name, ein Portal und erlaubte Initiators achtet, umgeht die typischen Stolpersteine. Danach ist das Plugin angenehm unsichtbar.

Weitere Details, Optionen und Troubleshooting stehen im GitHub-Repository des Plugins.