TrueNAS Stable Version Documentation
This content follows TrueNAS 24.10 (Electric Eel) releases. Use the Product and Version selectors above to view content specific to a different software release.
24.10 (Electric Eel) Version Notes
32 minute read.
24.10 Electric Eel
24.10 (Electric Eel) brings many new features and improvements to the TrueNAS experience:
The TrueNAS Apps feature backend moves from Kubernetes to Docker to streamline App deployment and management (announcement). Custom App deployment of Docker images is available via a guided wizard or a Compose YAML file.
Extend a RAIDZ vdev with individual disks (OpenZFS feature sponsored by iXsystems).
New TrueCloud Backup Tasks with streamlined functionality for Storj iX cloud backups and restoration.
New global search for finding pages and settings in the TrueNAS UI.
Dashboard reworked with more widgets, data reporting, and customization.
UI support for NVMe S.M.A.R.T. tests.
Align Enclosure Management code with 13.3 and improve feature performance.
Preserve SMB alternate data streams when ingesting data from remote servers.
Rewrite TrueNAS installer to better support future development efforts.
Polish UI table presentation and integrate with global search (NAS-127222).
Replace nslcd with sssd to improve Kerberos, NFS, and SMB support in non-AD environments (NAS-127073).
Generate a unique system ID for each install (NAS-123519).
ZFS Fast Deduplication (OpenZFS feature sponsored by iXsystems): This feature is partially present in TrueNAS, but is considered experimental and disabled by default in 24.10. Full UI integration is anticipated in a future TrueNAS release (NAS-127088).
24.10 (Electric Eel) is available from the TrueNAS download page.
For adventurous users that want to experiment with the latest feature development, nightly build .iso and .update files are available.
More details are available from Software Releases.
The release names and dates provided here are tentative and can change at any time.
SCALE™ | Enterprise™
Previous
Current
Next
TrueNAS SCALE 25.04 - Fangtooth
Latest:Anticipated:
TrueNAS is an appliance built from specific Linux packages. Updating TrueNAS using
aptor any method other than the TrueNAS web interface can make the system inoperable.Modifying the base OS can cause unexpected behavior during upgrades:
All auxiliary parameters can experience changes between TrueNAS major versions due to security and development changes. We recommend removing all auxiliary parameters from TrueNAS configurations before upgrading as these settings can result in SMB share failures after an upgrade.
- After updating, clear the browser cache (CTRL+F5) before logging in to SCALE. This ensures stale data doesn’t interfere with loading the SCALE UI.
24.10 moves the applications backend from Kubernetes to Docker (announcement).
All applications available from official catalogs in 24.04 are available to install in 24.10. Supported catalog applications automatically migrate to Docker deployments on upgrade from from 24.04 (Dragonfish) to Electric Eel. Applications from third-party catalogs, such as TrueCharts, do not automatically migrate to 24.10. See Preparing for App Migration below for more information.
Custom applications based on Docker images can be installed using the installation wizard or a Docker Compose YAML file. See Installing Custom Applications for more information.
Automatic app migration on upgrade from 24.04 is at parity for all official catalog applications. A few applications might require manual migration steps, depending on the options enabled in 24.04. For more information, see the comments for Home Assistant and Tailscale.
During the migration process, 24.10 creates a hidden Docker dataset on the apps pool that is mounted at
/mnt/.ix-apps . TrueNAS then reads the stored Kubernetes app data in the previousix-applications dataset, ports them to Docker, and saves them in the new Docker dataset.App storage ix-volumes present in ix-applications are cloned under the new Docker dataset and promoted.
Because the previous ix-applications dataset is retained as is, 24.10 maintains the ability to roll back to your previous Dragonfish installation.
You can re-initiate a failed migration of any previously-installed Kubernetes apps to Docker at any time after upgrading to Electric Eel. From a shell session enter
midclt call -job k8s_to_docker.migrate poolname, where poolname is the name of the applications pool, for example tank.Custom applications installed using the TrueNAS UI in 24.04 automatically migrate on upgrade to 24.10. Custom applications with nonstandard networking, such as an external interface attached, migrate, but the interface configuration is discarded. Users can either use the base networking as is or configure custom Docker networking using a YAML custom app deployment, Dockge, or Portainer.
Starting in 24.10, TrueNAS does not include a default NVIDIA GPU driver and instead provides a simple NVIDIA driver download option in the web interface. This allows for driver updates between TrueNAS release versions.
Users can enable driver installation from the Installed applications screen. Click Configure > Settings and select Install NVIDIA Drivers. This option is only available for users with a compatible NVIDIA GPU and no drivers installed or for users who have previously enabled the setting.
Support for the deprecated LDAP Samba Schema is removed in 24.10. Users with both LDAP and SMB shares configured should migrate legacy Samba domains to Active Directory before upgrading to 24.10.
Electric Eel introduces redesigns of the UI Dashboard and View Enclosure screens with numerous improvements to system and enclosure management. The legacy Dashboard and View Enclosure screens are removed in the RC.1 release version.
SMB audit log entries are omitted by default from the System > Audit screen. To view SMB audit results, go to System > Services and click receipt_long Audit Logs for the SMB service or use advanced search on the main Audit screen to query SMB events.
TrueNAS Apps Support Timeline for 24.04 and 24.10Summary: Applications added to the TrueNAS Apps catalog before December 24, 2024, require updates to enable host IP port binding. These updates roll out on June 1, 2025, and require TrueNAS 25.04 (or later).
Due to breaking changes involved in enabling host IP port binding, June 1, 2025 is the deadline for automatic apps migration on upgrade. Migrate from 24.04 to 24.10 before June 1, 2025, to ensure automatic app migration.
Applications installed on 24.10 do not receive updates after June 1, 2025. To update or install new applications, any users still running TrueNAS Apps on 24.10 after June 1 must update TrueNAS to 25.04 (or later).
Timeframe App Migration
24.04 → 24.10App Migration
24.10 → 25.04Before June 1, 2025 ✅ Supported ✅ Supported After June 1, 2025 ❌ Not Supported ✅ Supported (no updates or installs until upgraded to 25.04)
To prepare applications for migration from Kubernetes to Docker, address the following configurations before upgrading to 24.10:
| Configuration | Action Needed |
|---|---|
| Outdated Applications | Update all applications to the latest available version in the TrueNAS catalog before migrating. |
| Host Path ACLs | Users with applications installed on 24.04 using host path volume mounts with Enable ACL selected and ACL Entries defined in the app configuration, must go to the Edit Application screen and set the Force Flag checkbox under ACL Options before updating to 24.10. This ensures the app fully migrates and does not encounter issues when the mount point has existing data. |
| Encrypted Dataset | TrueNAS shows a warning and explains that applications do not migrate to 24.10 when the ix-applications dataset is configured on a pool with an encrypted dataset (see NAS-131561). Relocate installed applications to an unencrypted pool on 24.04 before attempting to upgrade to 24.10. TrueNAS does attempt to migrate predefined encrypted host mount paths. |
| Third Party Applications | Applications from third-party catalogs, such as TrueCharts, do not support automatic migration to 24.10. Migration of third-party applications generally requires manual data backup and redeployment. Third-party catalogs are provided, maintained, and supported by individuals or organizations outside of iXsystems. Refer to the catalog maintainer or the TrueNAS Community forums for migration support. |
| Container Dependent Network Settings | Applications do not migrate if TrueNAS network settings are configured to depend on any client container or application hosted on the TrueNAS system, such as DNS services, proxy networks, firewalls, and routers (see NAS-131553). This is an unsupported configuration because TrueNAS cannot access the necessary networks during boot if the client container has not started. |
With a stable release, upgrading to TrueNAS 24.10 (Electric Eel) from an earlier release is primarily done using the web interface update process. Another upgrade option is to use an .iso file to perform a fresh install on the system and then restore a system configuration file.
The chart below shows recommended paths for upgrading from earlier TrueNAS versions.
Update the system to the latest maintenance release of the installed major version before attempting to upgrade to a new major version.
Permitted upgrade methods are:
- update: apply an automatic update using the Update screen in the TrueNAS UI or install a manual update file. Some upgrade paths do not support these options (see chart).
- ISO install: save a current TrueNAS configuration file, perform a fresh install using an
.iso file for the target version, and then upload the previously saved configuration.
Users can skip major versions with a fresh ISO install followed by a configuration file upload. Carefully review release notes for each skipped major version before upgrading, noting any service deprecations or significant changes that impact the previous configuration. Consider stopping at major versions with significant impacts to address changes before continuing the upgrade path or be prepared to manually reconfigure incompatibilities on the latest target version.
This chart shows the basic update path to and from the latest release of each TrueNAS major version. Depending on your use case and risk tolerance, some users may prefer to remain on an earlier minor or major version for a period of time before updating. Visit the TrueNAS Software Status page for recommendations on which software version to use, tailored to user types ranging from Developer to Mission Critical.
flowchart LR
A["11.3-U5"] -->|update| B["12.0-U8.1"]
B -->|"update
ISO install"| C["13.0-U6.4
13.3-U1"]
C -->|ISO install| H
C -->|"(anticipated)"| I
D["22.02.4 (Angelfish)"] -->|update| E
E["22.12.4.2 (Bluefin)"] -->|update| F
F["23.10.2 (Cobia)"] -->|update| G
G["24.04.2.5 (Dragonfish)"] -->|update| H
H["24.10.2 (Electric Eel)"] -->|"(anticipated)"| I
I["25.04.0 (Fangtooth)"]
flowchart LR
A["11.3-U5"] -->|update| B
B["12.0-U8.1"] -->|update| C
C["13.0-U6.4"] -->|ISO install| F
C["13.0-U6.4"] -->|"(anticipated)"| G
D["23.10.2 (Cobia)"] -->|update| E
E["24.04.2.5 (Dragonfish)"] -->|update| F
F["24.10.2 (Electric Eel)"] -->|"(anticipated)"| G
G["25.04.0 (Fangtooth)"]
TrueNAS Enterprise
When attempting to migrate from TrueNAS 13.0 (or 13.3 for community members), the general recommendation is to back up the system configuration file and use an .iso file to fresh install TrueNAS. Upgrade your system to the latest publicly-available 13.0-U6.2 (or later) release before attempting to migrate. After install, restore the system configuration and import the pools.
Depending on the specific system configuration, this can be a straightforward or complicated process. See the Migration articles for cautions and notes about differences between each software and the migration process.
The only path to side-grade or migrate from 13.0-U6.2 or 13.3 is to install or upgrade to 24.04 (latest).
TrueNAS 24.10 and later releases do not support migrations from 13.X. These migrations cannot be done, and either fail or result in error conditions that cannot be resolved.
Download the
Component version numbers below are current as of the latest TrueNAS 24.10 release. Click the component version number to see the latest release notes for that component.
TrueNAS integrates many features provided by the upstream OpenZFS project. Any new feature flags introduced since the previous OpenZFS version that was integrated into TrueNAS (OpenZFS 2.1.11) are listed below:
| Feature Flag | GUID | Notes |
|---|---|---|
| raidz expansion | org.openzfs:raidz_expansion | |
| redaction list spill | com.delphix:redaction_list_spill |
For more details on feature flags, see OpenZFS Feature Flags and OpenZFS zpool-feature.7.
January 28, 2025
iXsystems is pleased to release TrueNAS 24.10.2! This is a maintenance release and includes refinement and fixes for issues discovered or outstanding after the 24.10.1 release.
- Do not retrieve hidden zpool properties in
py-libzfsby default (NAS-132988). These properties include name, tname, maxblocksize, maxdnodesize, dedupditto and dedupcached. Users needing these properties can see the linked ticket for thezpoolcommand to retrieve them. - A Force Remove iXVolumes checkbox is exposed on app deletion for any apps migrated from 24.04 that were unable to be deleted due to a “dependent clones” error (NAS-132914).
- New cloud backup option: Use Absolute Paths (NAS-132920).
- Fix loading the
nvidia_drmkernel module to populate the/dev/dridirectory for NVIDIA GPU availability in apps like Plex (NAS-133250). - Fix
netbiosnamevalidation logic if AD enabled (NAS-133167). - Disallow specifying SSH credentials when rsync mode is MODULE (NAS-132874 and NAS-132928).
- Simplify CPU widget logic to fix reporting issues for CPUs that have performance and efficiency cores (NAS-133128).
- Properly support OCI image manifest for registries other than Docker (NAS-133046).
- Remove explicit calls to the
syslog.syslogmodule (NAS-132657). - Fix an ACL Editor Group/User Search Bug (NAS-131841).
- Prevent infinite recursion on corrupted databases when deleting network interfaces (NAS-132567).
- Clean up FTP banner to prevent Reolink camera failures (NAS-132701).
- Refresh cloud sync credentials even if cloud sync task fails (NAS-132851).
- Fix lagg (bond) alert (NAS-133113).
- Make recovery attempt when initializing directory services (NAS-133235).
- Fix extend window not showing up for spares (NAS-133299).
- Remove stale locks before any TrueCloud Backup operation (NAS-132612).
Click here for the full changelog of completed Jira tickets that are included in the 24.10.2 release.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
We are aware of an issue affecting SED disk unlock at boot, particularly for systems configured with per-disk SED passwords. A fix is expected in the TrueNAS 25.04 release.
Some users who have applications with have NVIDIA GPU allocations report the error
Expected [uuid] to be set for GPU inslot [<some pci slot>] in [nvidia_gpu_selection])(see NAS-132086).Users experiencing this error should follow the steps below for a one time fix that should not need to be repeated.
Connect to a shell session and retrieve the UUID for each GPU with the command
midclt call app.gpu_choices | jq.For each application that experiences the error, run
midclt call -job app.update APP_NAME '{"values": {"resources": {"gpus": {"use_all_gpus": false, "nvidia_gpu_selection": {"PCI_SLOT": {"use_gpu": true, "uuid": "GPU_UUID"}}}}}}'Where:APP_NAMEis the name you entered in the application, for example “plex”.PCI_SLOTis the pci slot identified in the error, for example “0000:2d:00.0”.GPU_UUIDis the UUID matching the pci slot that you retrieved with the above command.
Click here to see the latest information on Jira about public issues discovered in 24.10.2 that are being resolved in a future TrueNAS release.
Click to expand
December 17, 2024
iXsystems is pleased to release TrueNAS 24.10.1! This is a maintenance release and includes refinement and fixes for issues discovered after the 24.10.0 and 24.10.0.X releases.
- The
sendmailcommand is removed for security reasons (NAS-133174). Users previously using sendmail as part of their custom scripting should useeximinstead. - The boot pool is now properly enforcing the default
setuidandnoexecoptions (NAS-127825). This restores the default boot pool behavior to be restricted from general use. Users that are currently attempting to exec scripts from a/homeor other boot pool location should move these to a data pool location. - Fix issue with zpl_get_name (NAS-132930). This can improve performance in some specific NFS workloads with large directories (see the commit for more details).
- Rework Dashboard CPU widgets to show metrics per physical core (NAS-131839).
- Prevent incorrect translation of LDAP Base DN to kerberos realm (NAS-132192).
- Increase the maximum permitted Samba (SMB) ACL size from 64 to 1024 entries (NAS-132344).
- Prevent applications service failing after upgrade if an app requires an Nvidia GPU (NAS-132070 and NAS-132131).
- Cache installed Nvidia kernel modules on upgrades within the same release train (i.e. 24.10.0, 24.10.1, etc.) so they do not need to be reinstalled and compiled (NAS-132359).
- Allow limited administrative users to view and download logs of certain jobs, even if they did not initiate the job (NAS-132031).
- Ensure installed apps are shown correctly after system reset (NAS-131913).
- Prevent
KeyError: 'pool_name'resulting from pool name collision in zpool.status (NAS-132742). - Allow unsetting/changing the apps pool in cases where the ix-apps dataset no longer exists (NAS-132065).
- Fix memory context for IPC read allocations to prevent potential Use After Free (UAF) corruption (NAS-132685).
- Make sure helm secret is safely serialized when listing App backups to migrate (NAS-132077). This fix prevents a Unicode decode error,
Failed to list backups: 'utf-8' codec can't decode byte 0xa6 in position 0: invalid start byte, that prevented some users from migrating apps from 24.04 to 24.10.0.X versions.
Click here for the full changelog of completed Jira tickets that are included in the 24.10.1 release.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
The Plex app doesn’t show Nvidia GPUs being passed to the app and transcode stops working (NAS-133250). A fix is anticipated in a future release and the linked Jira ticket has a workaround for the 24.10.1 release.
Configured SED drives do not migrate from FreeBSD-based TrueNAS releases to 24.10 (or earlier) releases, due to differences in how FreeBSD-based and Linux-based TrueNAS releases manage SED configurations. A fix to allow cleaner migrations of SED configurations is anticipated in TrueNAS 25.04.
The Dashboard CPU widgets have an issue displaying metrics for some types of hyper-threaded CPUs (NAS-133128). This is being addressed in future 24.10 maintenance releases.
An issue was discovered with restoration of ZFS snapshots via TrueCloud back up tasks (NAS-132608). The Take Snapshot option for TrueCloud back up tasks is disabled in 24.10.1 until the underlying issue is addressed in a future TrueNAS release.
OAuth support for Microsoft Outlook is no longer supported in 24.10 due to Microsoft removal of username and password authentication to their email server. Restoration of Outlook OAuth support is anticipated in the 25.04 release version (NAS-132807).
An issue has been discovered for cloud sync tasks configured with Filename Encryption, which is available in Advanced Remote Options (NAS-132472). As this is an upstream issue in rclone, we recommend that users should not create new cloud sync tasks with Filename Encryption enabled. Existing users of this feature must leave it enabled for existing cloud sync tasks to be able to recover backups.
Some users report an error when trying to delete applications that previously migrated from 24.04 to 24.10 and are configured with ixVolumes (NAS-131911). Attempting to delete an affected app returns the error
Failed to delete dataset: cannot destroy 'POOL/ix-apps/app_mounts/APPNAME': filesystem has dependent clones. A fix is expected in the 24.10.2 release (NAS-132914).VMs might not start due to an issue with memory allocation and the ZFS cache (NAS-128544). This is resolved in the upcoming TrueNAS 25.04 version.
If an SMB or NFS bind IP address is set and an administrator changes the host system IP without first removing the current NFS and/or SMB bind IP, the UI does not display the current NFS and/or SMB bind ip address(es) and provides no mechanism for unsetting the bad IP address (NAS-133049). This breaks functionality of the NFS and/or SMB service.
Users who encounter this bug can manually remove the existing bind IP address(es) and then use the TrueNAS UI to reconfigure bind IP addresses. Connect to a TrueNAS shell session and enter one or both of these command(s), as needed:
midclt call smb.update '{"bindip": []}'to clear the SMB bind address(es)midclt call nfs.update '{"bindip": []}'to clear the NFS bind address(es)
A UI fix for this issue is expected in a future release.
-
TrueNAS EnterpriseAn issue was found with configuring Chelsio T580 NICs in different modes with TrueNAS 24.10.1. This is under investigation and a fix is forthcoming in a future 24.10 maintenance release.
Click here to see the latest information on Jira about public issues discovered in 24.10.1 that are being resolved in a future TrueNAS release.
Click to expand
October 29, 2024
iXsystems is pleased to release TrueNAS 24.10.0! This is the first stable release of TrueNAS SCALE 24.10 (Electric Eel). It includes numerous software component updates and polished features, as well as fixes for issues discovered in 24.10-RC.1 and 24.10-RC.2.
True Cloud Backup Tasks (NAS-127165).
Replace nslcd with sssd (NAS-127073).
Dashboard Improvements (NAS-127217).
UI Table Improvements (NAS-127222).
UI Global Search (NAS-127224).
Rewrite enclosure plugin in 24.10 to match performance improvements in 13.3 (NAS-123474).
Prevent phantom partitions that TrueNAS erroneously reported as disconnected pools (NAS-131171).
Revised Docker networking logic for applications (NAS-131617).
Enable editing of custom YAML applications (NAS-131147).
Prevent the TrueNAS UI from sending an improper payload for the Outboard Activity option when re-saving an edit to global network settings (NAS-131787).
When moving from an existing applications pool to a new pool, TrueNAS does not present the option to Migrate applications to the new pool because the underlying functionality is not present in the new Docker apps framework (NAS-131610). Users who need to redeploy the applications pool can either choose to leave existing applications on the previous location, remove existing applications and reinstall on the new pool, or manually relocate and clean up data.
Documentation Hub Update: To reflect the continuing process of application maintenance and updates as separate from TrueNAS major version releases, all application Tutorials are moved from the Tutorials section in TrueNAS version documentation to a dedicated and unversioned TrueNAS Apps section.
Community contributions to TrueNAS Apps documentation are highly encouraged! The Community Apps documentation is pre-populated with placeholder templates for each application available in the TrueNAS Community train and ready to accept Pull Requests. See Contributing to TrueNAS Application Documentation for more information.
Click here for the full changelog of completed Jira tickets that are included in the 24.10.0 release.
To switch between detail and list views for the changelog, press t.
Open the changelog in Jira to see the Export menu to print or download the changelog in various file formats.
SED devices are not consistently unlocking on system restart (NAS-132518). Users are cautioned to avoid using SED devices in 24.10 or attempting to migrate a functional SED environment from TrueNAS 13.0-U6.3 (Enterprise) or TrueNAS 13.3-U1 (Community) until this issue is resolved.
A bug with sudo v1.9.13 causes commands like
sudo su -andsudo subefore starting tmux to break in TrueNAS 24.10. Sudo v1.9.14 fixes this issue and is planned for inclusion in a future TrueNAS release.Application Update Available tooltips display the current installed version as the available update version (NAS-131747). A fix for this issue is expected in the 24.10.1 release version.
Installed custom applications do not alert for available updates in the TrueNAS UI (NAS-132202). A fix for this issue is expected in the 24.10.1 release version.
Some users who have upgraded to 24.10.0 from a previous version, and who have applications with have NVIDIA GPU allocations, report the error
Expected [uuid] to be set for GPU inslot [<some pci slot>] in [nvidia_gpu_selection])(see NAS-132086).Users experiencing this error should follow the steps below for a one time fix that should not need to be repeated.
Connect to a shell session and retrieve the UUID for each GPU with the command
midclt call app.gpu_choices | jq.For each application that experiences the error, run
midclt call -job app.update APP_NAME '{"values": {"resources": {"gpus": {"use_all_gpus": false, "nvidia_gpu_selection": {"PCI_SLOT": {"use_gpu": true, "uuid": "GPU_UUID"}}}}}}'Where:APP_NAMEis the name you entered in the application, for example “plex”.PCI_SLOTis the pci slot identified in the error, for example “0000:2d:00.0”.GPU_UUIDis the UUID matching the pci slot that you retrieved with the above command.
Drives that have been formatted with previous TrueNAS versions can show exported pools in the TrueNAS UI (NAS-131890). This is typically due to obsolete filesystem labels in the boot drives still being detected by TrueNAS. The underlying bug is fixed in 24.10.0-RC.2 and newer, but these labels can remain on boot drives used with previous TrueNAS releases. Removing these labels from the boot drives requires backing up your TrueNAS configuration, reinstalling 24.10.0 fresh on the boot drives, then restoring the TrueNAS configuration.
If TrueNAS is updated to 24.10.0 from a previous 24.10 release candidate version and the Install Nvidia Drivers option is selected, TrueNAS downloads and installs drivers to the upgraded OS in the background before starting the Applications service (NAS-132070). This can be a lengthy process with no UI progress feedback. If a network interruption on boot prevents driver installation, TrueNAS does not retry and a manual workaround is required (see linked NAS issue for steps).
-
TrueNAS EnterpriseThere is a known issue with the ES24 expansion shelf not displaying on the Enclosure Management screen in 24.10.0. A fix is anticipated in the next 24.10 release. In the meantime, customers with an ES24 shelf connected to their TrueNAS appliance should plan their 24.10 upgrade time frame for the first maintenance release, 24.10.1.
Click here to see the latest information on Jira about public issues discovered in 24.10.0 that are being resolved in a future TrueNAS release.