TrueNAS Stable Version Documentation
This content follows TrueNAS 25.04 (Fangtooth) releases.
Use the Product and Version selectors above to view content specific to a different software release.
25.04 (Fangtooth) Version Notes
31 minute read.
25.04 Fangtooth
TrueNAS 25.04 (Fangtooth) brings many new features and improvements to the TrueNAS experience:
NFS over RDMA support (Enterprise Feature - see Configuring the NFS Service)
Fibre Channel support (Enterprise Feature)
iSCSI XCOPY support through ZVOL block cloning (NAS-130017).
Versioned TrueNAS JSON-RPC 2.0 over WebSocket API with new and improved API documentation (see API Reference)
User-linked API Keys (see Managing API Keys)
Improved UI Login Experience (NAS-130810)
Improved STIG Compliance and Security Focus (Enterprise Feature - NAS-127235)
Enable support for ZFS Fast Deduplication (NAS-127088)
(Updated for 25.04.2) New experimental Containers feature.
TrueNAS 25.04 introduces support for Linux system containers (LXC), enabling lightweight isolation similar to jails in TrueNAS CORE.
Containers are an experimental feature intended for community testing only.
(Updated for 25.04.2) Reintroduced “classic virtualization” with the Virtual Machines feature.
Improvements to the TrueNAS apps service, including per-app selection of IP addresses (See TrueNAS Apps in the Upgrade Notes).
For adventurous users who want to experiment with the latest feature development, 25.04 (Fangtooth) nightly images are available from the TrueNAS downloads server.
More details are available from Software Releases.
The release names and dates provided here are tentative and can change at any time.
| 
Previous
Current
Next
TrueNAS 25.10 - Goldeye
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 unexpected behavior such as SMB share failures after an upgrade.
SSH auxiliary parameters are unsupported. Certain configurations can prevent the SSH service from starting.- After updating, clear the browser cache (CTRL+F5) before logging in to TrueNAS. This ensures stale data doesn’t interfere with loading the TrueNAS UI.
- The TrueNAS REST API is deprecated in TrueNAS 25.04. Full removal of the REST API is planned for a future release.
TrueNAS 25.04 and later uses a versioned JSON-RPC 2.0 over WebSocket API. API versions are numbered in conjunction with TrueNAS version releases.
The API documentation provides information about supported API methods and events. Documentation is included for all API versions supported by the current TrueNAS release and defaults to the latest supported API. Use the dropdown to view documentation for different supported API versions.
Advanced users can interact with the TrueNAS API to perform management tasks using the TrueNAS API Client as an alternative to the TrueNAS web UI. This websocket client provides the command line tool
midcltand allows users to communicate with middleware using Python by making API calls. The client can connect to the local TrueNAS instance or to a specified remote socket.You can access TrueNAS API documentation in the web interface by clicking laptop My API Keys on the top right toolbar account_circle user settings dropdown menu to open the User API Keys screen. Click API Docs to view API documentation.
25.04 also introduces user-linked API access keys, allowing administrators to configure per-user access to the TrueNAS API. Keys are revocable and can be configured to automatically expire on a preset date.
Active Directory/LDAP user-linked API key support is available to TrueNAS Enterprise customers only.User-linked API keys allow for better integration of TrueNAS into third-party solutions. Use this as a reference for projects that require direct TrueNAS integration.
Always back up and secure keys. TrueNAS displays the key string only once, in the API Key confirmation dialog, immediately after creation.
User-linked API keys allow password-equivalent access to the TrueNAS middleware. API keys are not subject to the two-factor authentication (2FA) configuration of the associated user account. A compromised API key results in access to the TrueNAS API as the associated user, even if the account is configured to require 2FA.
For increased security, HTTPS with SSL/TLS transport security is required for TrueNAS API authentication using API keys. TrueNAS automatically revokes any user-linked API keys passed as part of an authentication attempt via insecure (HTTP) transport. A revoked API key cannot be used until it is reset. Resetting generates a new key-string.
Remember to update clients to use the new key.
See Managing API Keys for more information.
Legacy API keys created in TrueNAS 24.10 or earlier migrate to the root, admin, or truenas_admin account, depending on server configuration.
Existing API keys created via the TrueNAS API (not UI or TrueCommand) that specify an allow list with white-listed API methods are revoked upon upgrade because there is no clean way to migrate to the new system. Administrators should create a service account (a user account for this particular purpose), define desired access rights for this service account, generate a new user-linked API key, and distribute it to the API client.
In TrueNAS 25.04 (and later), users must log in as a system administrator with full administrative access to upload or download a system configuration file. Other users, including restricted admin accounts such as a shares administrator, cannot perform database operations. See Using Administrator Logins for more information on admin account types.
The built-in Netdata UI, accessible from the Netdata button on the Reporting screen in TrueNAS 24.04 and 24.10, is removed in TrueNAS 25.04 (and later) for security hardening. Users wishing to continue using the Netdata UI to monitor system reports can install the Netdata application.
Virtual Machines and Containers in TrueNAS 25.04TrueNAS 25.04 introduces support for Containers (Linux system containers), enabling lightweight isolation similar to jails in TrueNAS CORE.
TrueNAS 25.04.2 reintroduces “classic virtualization” with the Virtual Machines feature.
Virtual machines in 25.04.2 (or later) are created and appear on the Virtual Machines screen.
VMs created in 25.04.0 or 25.04.1 using the Instances feature continue to function and appear on the Containers screen.
VMs created in 24.10 or earlier are located depending on migration path:
You do not need to migrate existing VMs from the Containers screen to the Virtual Machines screen at this time. We are developing additional guidance for these legacy VMs for the TrueNAS 25.10 release.
We are actively updating Tutorials and UI Reference articles to reflect these changes. Please use the Docs Hub Feedback button (located to the right of any article) to report documentation issues or request improvements to the Containers or Virtual Machines documentation.
Containers (Linux system containers) are an experimental feature intended for community testing only. Functionality could change significantly between releases, and containers might not upgrade reliably. Use this feature for testing purposes only—do not rely on it for production workloads. Long-term stability is planned for future TrueNAS Community Edition releases.
Make all configuration changes using the TrueNAS UI. Operations using the command line are not supported and might not persist on upgrade.
For assistance or to discuss this feature with other TrueNAS users, visit our community forums.
To report bugs, submit an issue on TrueNAS Jira.
Application maintenance, including version updates, features, and configuration options, is independent from TrueNAS version release cycles.
See documentation and resources at the TrueNAS Apps Market and the truenas/apps repository issues tracker for more information.
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.
Due to breaking changes involved in enabling host IP port binding, June 1, 2025 is the deadline for automatic apps migration from 24.04 to 24.10 on upgrade. Migrate from 24.04 to 24.10 before June 1, 2025, to ensure automatic app migration.
Upgrade to 24.10.2.2 or 25.04 before June 1 to continue receiving regular app updates. Previously installed apps on TrueNAS 24.10.2.1 (or earlier) do not receive updates after this point. Normal application update functionality resumes after TrueNAS updates to 24.10.2.2 or 25.04.
Timeframe App Migration
24.04 → 24.10App Updates in 24.10 App Migration
24.10 → 25.04App Updates in 25.04 Before June 1, 2025 ✅ Supported ✅ Supported ✅ Supported ✅ Supported After June 1, 2025 ❌ Not Supported ✅ Supported
(24.10.2.2 or later)✅ Supported ✅ Supported
With a stable release, upgrading to TrueNAS 25.04 (Fangtooth) from an earlier TrueNAS release is primarily done using the web interface update process. Another upgrade option is to use a TrueNAS .iso file to perform a fresh install on the system and then restore a system configuration file.
Migrating to 25.04 from FreeBSD-based TrueNAS 13.0 or 13.3 is primarily done using an .iso fresh install and config file restore. See Migrating from TrueNAS 13.0 or 13.3 below and the migration guide to prepare your system for migration.
TrueNAS Enterprise
TrueNAS Enterprise customers with High Availability (HA) or Non-HA TrueNAS Hardware should consult with TrueNAS Enterprise Support for assistance before attempting to migrate.
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.8
13.3-U2"]
C -->|update| G
C -->|ISO install| 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.3 (Electric Eel)"] -->|update| I
I["25.04.2 (Fangtooth)"]
flowchart LR
A["11.3-U5"] -->|update| B
B["12.0-U8.1"] -->|update| C
C["13.0-U6.8"] -->|ISO install| F
C -->|update| E
D["23.10.2 (Cobia)"] -->|update| E
E["24.04.2.5 (Dragonfish)"] -->|update| F
F["24.10.2.3 (Electric Eel)"] -->|"(anticipated)"| G
G["25.04 (Fangtooth)"]
Migrating TrueNAS from FreeBSD- to Linux-based versions is a one-way operation. Attempting to activate or roll back to a FreeBSD-based TrueNAS boot environment can break the system.
Upgrade your FreeBSD-based TrueNAS system to the latest publicly-available 13.0 release version (or 13.3 for community users) before attempting to migrate. See Software Releases for current recommended update paths to make sure you download and migrate to the correct version.
Depending on the specific system configuration, migrating from a FreeBSD-based TrueNAS version can be a straightforward or complicated process. See the Migration articles for cautions and notes about differences between each software and the migration process.
Click the component version number to see release notes for that component.
| 25.04.2 | 25.04.1 | 25.04.0 | 25.04-RC.1 | 25.04-BETA.1 | |
|---|---|---|---|---|---|
| Linux Kernel | 6.12.15 | 6.12.15 | 6.12.15 | 6.12.15 | 6.12.9 |
| OpenZFS | 2.3.0-1 | 2.3.0-1 | 2.3.0-1 | 2.3.0-1 | 2.3.0-1 |
| Docker Engine | 27.5.0 | 27.5.0 | 27.5.0 | 27.5.0 | 27.5.0 |
| NVIDIA Driver | 550.142 | 550.142 | 550.142 | 550.142 | 550.142 |
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.2.99) are listed below:
| Feature Flag | GUID | Notes |
|---|---|---|
| fast deduplication | com.klarasystems:fast_dedup | This flag is present in 24.10, but is now generally available through the TrueNAS UI. |
For more details on feature flags, see OpenZFS Feature Flags and OpenZFS zpool-feature.7.
August 7, 2025
The TrueNAS team is pleased to release TrueNAS 25.04.2.1! This is a small maintenance release that includes several debug and audit optimizations to community features.
- Fixes an issue where upgrading from Electric Eel would break the Virtual Machines page for existing VMs without configured VNC passwords or VMs configured to use display device ports outside the standardized range of 5900-65535 (NAS-136941).
- Prevents standby controller from updating
nsswitch.confwith directory services to avoid blocking NSS lookups before the system is fully configured (NAS-136994). - Optimizes debug generation and audit features as part of this release.
July 31, 2025
The TrueNAS team is pleased to release TrueNAS 25.04.2! This is a maintenance release and includes refinements and fixes for issues discovered after 25.04.1.
TrueNAS 25.04.2 is not recommended for TrueNAS Enterprise customers with High Availability (HA) systems at this time.
- STIG enforces the limit of three consecutive invalid login attempts by a user in 15 minutes, and limits the maximum number of concurrent session to 10 for all accounts and/or account types (NAS-127189).
- Adds a new SMB share preset Veeam Repository with Fast Clone to the share Purpose list of options. Requires creating a new share and dataset prior to adding a Veeam Backup & Restore repository, and setting the dataset ZFS record size to 128 KiB. There is currently no supported mechanism to convert an existing SMB Veeam repository into a Veeam Repository Share with fast clone (NAS-135244).
- Changes to Support notifications for zpool capacity, warning, and critical alerts (85, 90, and 95% respectively) and removes “optimal pool performance” language from the notifications to address customer concerns with over-notification on issues that do not interest them (NAS-135831).
- Changes PSU failures that occur in the field to automatically generate a support alert (NAS-135832).
TrueNAS 25.04.2 reintroduces “classic virtualization” with the Virtual Machines feature. Virtualization features are now split between the Virtual Machines and Containers screens.
Virtual machines created in 25.04.0 or 25.04.1 using the Instances feature continue to function and appear in the Containers screen. New VMs and those migrated from 24.10.2.2 to 25.04.2 use the Virtual Machines screen.
Virtual machines automatically migrate from TrueNAS 24.10 to 25.04.2. No manual migration of virtual machines is required.
Adds the ability to enter optional custom endpoints in cloud sync credentials that support Global and Select tiers in Storj (NAS-133835).
Adds a Secure Boot checkbox to the Add Virtual Machine wizard and Edit Virtual Machine form (NAS-136466).
Passes the Storj/iX cloud sync credential access key and secret access key in the UI when creating the credential (NAS-135837).
Removes the Mega cloud service provider for rclone. Mega Technical Support states they no longer support rclone due to bugs in their implementation and requirements to properly troubleshoot issues (NAS-135844).
Adds the
ethtool -mto the debug file, which brings additional layer1 troubleshooting to interfaces (NAS-135911).Shows all object fields and explicitly lists all parameters and result fields for nested objects not previously included in generated API documentation (NAS-135959).
Adds starting and stopping services in the UI to the audit log records (NAS-136310).
Click here for the full changelog of completed tickets that are included in the 25.04.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.
NAS-136941 - Virtual Machines: Cannot Retrieve Response UI response on Virtualization UI.
- Impacts: VMs that were created without VNC passwords on older TrueNAS releases where this was not required.
- Workaround: Rollback to 24.10 and apply password to display device for the VM(s) before updating.
- Impacts: VMs with a VNC port configured outside the display device port range (>=5900 <=65535). This can impact VMs created prior to the port range validation implementation.
- Workaround: Rollback to 24.10 and adjust VM VNC ports to be within range 5900 - 65535 before updating.
NAS-136939 - Historic VM entries on systems migrated prior to 25.04.2 may be seen in Virtualization table.
- Impacts: VMs created prior to 25.04 which were upgraded to 25.04 releases prior to 25.04.2 may see historic records in the virtualization table.
- Workaround: Usually the errors are “ENOENT” because the underlying resources were deleted after the user migrated these to incus. The historic entries can be deleted.
Some users of TrueNAS Apps attempting to configure GPU allocation report the error
Expected [uuid] to be set for GPU inslot [<some pci slot>] in [nvidia_gpu_selection])(see (NAS-134152).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 -j 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.
Custom applications with TTY enabled do not display logs in the TrueNAS UI. This is due to an upstream bug, see https://github.com/docker/docker-py/issues/1394. Users experiencing this issue can resolve it by either disabling TTY or using
docker logsfrom the command line.TrueNAS UI displays Updates Available button after updating to the latest release (see (NAS-136046). This issue is resolved in the upcoming 25.04.2 release, but if you want to work around this issue now, follow these steps:
- Open the Shell and run
midclt call systemdataset.config | jq ."path" - Search for a file named update.sqsh in the returned string using
find "returned path" -name update.sqsh - Run
rm -f <full-path-to-update.sqsh>, replacing<full-path-to-update.sqsh>with the full file path to the update.sqsh file from the previous step
- Open the Shell and run
- SSH auxiliary parameters are unsupported. Certain configurations can prevent the SSH service from starting.
Click here to see the latest information about public issues in 25.04.1 that are being resolved in a future TrueNAS release.
Click to expand
May 27, 2025
The TrueNAS team is pleased to release TrueNAS 25.04.1! This is a maintenance release and includes refinements and fixes for issues discovered after 24.04.0.
- Support for account policy settings in TrueNAS Enterprise environments regarding password history, complexity, and aging (NAS-135115). Note: Administrators should contact TrueNAS Support before enabling STIG and FIPS security settings (see Security Settings for details).
- Add PAM-based session management for middleware (NAS-127189). For STIG compliant environments, the max number of simultaneous logins is 10. Accounts are locked for 15 minutes after 3 consecutive failed login attempts.
- Remove support for BOTH in share ACLs (NAS-135183).
- Persist updated GMail OAuth refresh token to prevent deauthentication (NAS-135394).
- Improvements to Instances, including:
- Allow the same host path to be mounted inside multiple containers (NAS-135371).
- ARC scaling and eviction fixes to prevent VM crashes due to OOM errors (NAS-135904).
- Enhanced robustness of the Instances screen to handle edge-case configurations (NAS-135098).
- Add a synthetic container root user (NAS-135375). This adds a built-in unprivileged root user for containers: truenas_container_unpriv_root. This account can be used in permissions related APIs / UI forms to grant permissions aligning to root in VMs and containers (see Managing Instance Permissions).
- Improved error handling when instance ports conflict with other service or application configurations (NAS-134963).
- Prevent accidental deletion of built-in idmap entries (NAS-135475).
- Improved validation for attaching and removing zvols from instances (NAS-135308).
- Increase middlewared.service timeout to prevent boot failure when upgrading systems with slow boot drives (NAS-135663).
- Prevent JSON decode crash in smartctl output to fix issues with disk temperature reporting (NAS-135527).
- Fix TrueNAS UI authentication with IPv6 entries in Allowed IP Addresses (NAS-135361).
- Fix SSH service startup with auxiliary parameters enabled (NAS-135367).
- Improve human-readable formatting of TrueCloud Backup log (NAS-134491).
- Change how oplocks are handled for multiprotocol shares (NAS-135040). Removes kernel oplocks in favor of disabling oplocks on a per-share basis when they have been flagged for mixed-mode use. This avoids issues observed in the field with kernel lease breaks causing client timeouts as well allowing SMB leases globally, resolving limitations on multiprotocol shares and Time Machine backup seen in 25.04.0.
- Fix API calls when connected to legacy
/websocketendpoints (NAS-135643).
Click here for the full changelog of completed tickets that are included in the 25.04.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.
SSH auxiliary parameters are unsupported.
Certain configurations can prevent the SSH service from starting.
An update to the Microsoft Netlogon RPC protocol affects systems using the “AD” idmap backend for Active Directory. Users are not able to connect to the SMB service provided by Samba for any domain configured to use the “AD” idmap backend. A fix is expected in the TrueNAS 25.04.2 release.
Some users of TrueNAS Apps attempting to configure GPU allocation report the error
Expected [uuid] to be set for GPU inslot [<some pci slot>] in [nvidia_gpu_selection])(see (NAS-134152).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 -j 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.
Custom applications with TTY enabled do not display logs in the TrueNAS UI. This is due to an upstream bug, see https://github.com/docker/docker-py/issues/1394. Users experiencing this issue can resolve it by either disabling TTY or using
docker logsfrom the command line.TrueNAS UI displays Updates Available button after updating to the latest release (see (NAS-136046). This issue is resolved in the upcoming 25.04.2 release, but if you want to work around this issue now, follow these steps:
- Open the Shell and run
midclt call systemdataset.config | jq ."path" - Search for a file named update.sqsh in the returned string using
find "returned path" -name update.sqsh - Run
rm -f <full-path-to-update.sqsh>, replacing<full-path-to-update.sqsh>with the full file path to the update.sqsh file from the previous step
- Open the Shell and run
Click here to see the latest information about public issues in 25.04.1 that are being resolved in a future TrueNAS release.