Incus 6.16 Introduces a new TrueNAS Storage Driver which allows block oriented Incus storage pools to be created and used from a TrueNAS Scale dataset. Since TrueNAS Scale backend storage is zfs, this is particularly well suited for Incus.
The driver operates in a block-based manner, meaning that all Incus volumes are created as ZFS Volume block devices on the remote TrueNAS server. These ZFS Volume block devices are accessed on the local Incus node via iSCSI.
The driver relies on the truenas_incus_ctl tool to interact with the TrueNAS API to perform actions on the remote server. This tool also manages the activation and deactivation of remote ZFS Volumes via open-iscsi. If truenas_incus_ctl is not installed or available in the system’s PATH, the driver will be disabled.
So, a significant part of this tutorial is building and installing the truenas_incus_ctl utility that Incus 6.16 uses in the background.
I started this tutorial with TrueNAS Scale v25.04. However, I encountered issues which required me to upgrade to TrueNAS Scale v25.10 beta and everything worked great in that version.
The first step is to log into your TrueNAS Scale system and go to System – Services and turn on the iSCSI protocol and set iSCSI to start automatically when TrueNAS starts.
To use the TrueNAS Storage Driver for Incus, you must be running a minimum of Incus v6.16 on your Incus server.
You must also install iSCSI on your Incus Server.
sudo apt install open-iscsi -y
open-iscsi was previously installed on my Incus Server.
I have developed a script to automate the download, compilation and installation of the truenas-incus-ctl tool on your incus server.
nano install-truenas-incus-ctl.sh
Insert the following into the editor session.
#!/usr/bin/env bash
set -e
# --- Config ---
VERSION="v0.7.3"
REPO="https://github.com/truenas/truenas_incus_ctl.git"
INSTALL_DIR="/usr/local/bin"
echo "[1/5] Installing dependencies (Go + Git)..."
sudo apt update
sudo apt install -y golang-go git
echo "[2/5] Cloning truenas_incus_ctl repo..."
rm -rf /tmp/truenas_incus_ctl
git clone $REPO /tmp/truenas_incus_ctl
cd /tmp/truenas_incus_ctl
git checkout "$VERSION"
echo "[3/5] Building truenas_incus_ctl..."
go build -o truenas_incus_ctl .
echo "[4/5] Installing to $INSTALL_DIR..."
sudo install -m 0755 truenas_incus_ctl $INSTALL_DIR/
echo "[5/5] Verifying installation..."
command -v truenas_incus_ctl
truenas_incus_ctl --version || echo "Run 'truenas_incus_ctl --help' to confirm usage."
echo "✅ truenas_incus_ctl $VERSION installed successfully!"
As of this tutorial, the version of the tool is v0.7.3. If there is a later version when you are following this guide, you can update the version number. Do a CTRL O and enter to write the file out and a CTRL X to exit the nano editor.
Provide execute privilege to the script.
chmod +x install-truenas-incus-ctl.sh
Execute the script:
./install-truenas-incus-ctl.sh
Now go back to your TrueNAS Web Interface and click on your username in the upper right and select “My API Keys”.
Add an API key for use from your Incus server. Make sure and make a copy of the key because it will not be presented again for security reasons.
We are now ready to create a storage pool on your Incus Server that is hosted on your TrueNAS server. Here’s an example of the command I used on my Incus Server.
incus storage create truenas-storage truenas \
source=incus-tank \
truenas.host=172.16.1.115 \
truenas.api_key=1-SP4pWEzB9T1CgPQ9uPTpgiDStV496BCAqGLfHfqDWMYeglJ6mn9iu04RReGbkNmB \
truenas.allow_insecure=true
The source is the name of the pool/dataset on my TrueNAS Scale server where I want Incus to create the storage pool. The truenas.host is the IP address or domain name of your TrueNAS Scale server. The truenas.api_key is the key that we obtained from the TrueNAS server earlier.
Back on the TrueNAS server, you should now see your new pool/dataset.
When you list your storage pools you will see the new pool and that it uses the truenas driver.
To list the size/utilization of the pool:
incus storage info truenas-storage
To create a new container in the TrueNAS storage pool:
incus launch images:ubuntu/24.04 Test --storage truenas-storage
Keep in mind that the speed of your network adapters on both your Incus Server and your TrueNAS Server as well as the speed of the TrueNAS backend storage contribute to the performance of containers. iSCSI is a fast protocol. If you want to learn more about iSCSI, watch my video entitled iSCSI Fast Network Based Storage.
You can use the following incus list command to indicate the storage pool that your containers are in.
incus list -cnsb4tS
If you want to change the default pool in which containers are created to the new pool, you can edit your default profile.
incus profile edit default
In the editing session above, you could change the pool: default to pool: truenas-storage.
One of the advantages of hosting your incus storage pool in TrueNAS is that it might provide higher availablity storage depending on your TrueNAS configuration. A huge use-case for hosting a storage pool in TrueNAS is that all the members of an incus cluster can address the TrueNAS storage pool for realtime migration of Incus Virtual Machines between cluster members.
The TrueNAS Storage Driver for Incus is an additional option for those who are TrueNAS users. The only downside that I can imagine is that you must ensure that the TrueNAS Server is always available and accessible to the Incus Servers that rely upon TrueNAS storage.